{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"2e9ed469-2710-4af3-88b0-d6b5f9048988","name":"Welcome to the Circa API","description":"The Circa API is a set of [REST](http://en.wikipedia.org/wiki/Representational_state_transfer) APIs that enable you to programmatically manage Circa events and contacts.\n\nThis API reference contains all of our stable API features. These are fully operational and no breaking changes to the API will be made. We do make additive changes to our API so your application should adopt a permissive approach to parsing responses, ignoring any attributes your client doesn’t understand.\n\nWe use many standard HTTP features, like HTTP verbs, which can be understood by many HTTP clients. The API always returns responses in [JSON](https://www.json.org/) format, with some exceptions that support additional formats.\n\nThis documents all the REST API methods, with example requests and responses. You can also load this into the [Postman API Development Environment](https://www.getpostman.com/) to interact with the API with your own API key.\n\n# Data Types\n\nThe API can receive requests and return responses comprising of specific data types. For brevity in the rest of the documentation, the details of these data types are recorded in this section:\n\n##### String\n\nA `String` is a variable length UTF-8 encoded string.\n\n##### Date\n\nA `Date` is represented by a [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) compliant String with no time component:\n\n```\n2020-09-28\n\n```\n\nThis represents Monday 28th September 2020.\n\n##### Time\n\nA `Time` is represented by a [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) compliant String that is always UTC:\n\n```\n2020-09-28T14:30:00Z\n\n```\n\nThis represents Monday 28th September 2020 at 2:30PM UTC.\n\n##### Time Range\n\nAn object that describes a period of time between provided `min` and `max` Times. For example:\n\n```\n{\n  \"min\": \"2020-09-28T14:30:00Z\",\n  \"max\": \"2020-09-29T14:30:00Z\"\n}\n\n```\n\nBoth `min` and `max` should be specified.\n\n##### Boolean\n\nA `Boolean` has a value of `true` or `false`.\n\n##### Integer\n\nAn `Integer` is a 32-bit signed integer.\n\n##### Integer Range\n\nAn object that describes a range of integer numbers between provided `min` and `max` values. For example:\n\n```\n{\n  \"min\": 100,\n  \"max\": 200\n}\n\n```\n\nEither `min` or `max` should be specified.\n\n##### Float\n\nA `Float` is a 32-bit numeric with a decimal point.\n\n##### Float Range\n\nAn object that describes a range of float numbers between provided `min` and `max` values. For example:\n\n```\n{\n  \"min\": 100,\n  \"max\": 200\n}\n\n```\n\nEither `min` or `max` should be specified.\n\n##### User\n\nAn object with org member information. For example:\n\n```\n{\n  \"id\": \"VXNlci0x\",\n  \"first_name\": \"Aaron\",\n  \"last_name\": \"Beier\",\n  \"email\": \"admin@example.com\"\n}\n\n```\n\nAll the User fields are required.\n\n##### Pagination\n\nAn object with pagination information. For example:\n\n```\n{\n  \"current_page\": 1,\n  \"total_pages\": 2,\n  \"per_page\": 25,\n  \"total_entries\": 26\n}\n\n```\n\nIs returned as a response to \"List\" queries that support pagination.\n\n# Errors\n\nFor API responses, we use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that resulted from the provided information (e.g. a required parameter was missing, an event could not be found, etc.), and codes in the `5xx` range indicate an error with our servers.\n\n##### 200 OK\n\nThe request was successful.\n\n##### 201 Created\n\nThe request has been fulfilled and resulted in a new resource being created.\n\n##### 400 Bad Request\n\nThe request could not be understood by the server due to malformed JSON syntax.\n\n##### 401 Unauthorized\n\nThe request was refused as the API Key is missing or was not recognized.\n\n##### 402 Payment Required\n\nThe request was refused as your subscription has expired.\n\n##### 404 Not Found\n\nThe resource, such as an event, could not be found.\n\n##### 422 Unprocessable\n\nThe request was unable to be processed due to it containing invalid parameters.\n\nThe response will contain a JSON object containing one or more errors relating to the invalid parameters.\n\nFor example if when creating an event you omitted the required status field, you would receive a response like:\n\n```\n{\n  \"errors\": {\n    \"status\": [\n      \"should be one of COMMITTED, CONSIDERING, SKIPPING, CANCELLED, POSTPONED\"\n    ]\n  }\n}\n\n```\n\n##### 500 Server Error\n\nThe request was unable to be processed due to an error with our servers.\n\n# Authorization\n\nAPI Secret Key MUST be passed with each API request as a Bearer Authorization header. For example:\n\n```\nGET /api/v1/teams\nHost: app.circa.co\nAuthorization: Bearer {API_KEY}\n\n```\n\nAPI Key should be kept secret. You can find the API key for your org in [Org Settings > Integrations > API](https://app.circa.co/settings/integrations/api) page:\n\n![](https://cdn.filestackcontent.com/AHVDICkXSpQTi71xXc7w)\n\n# Push Notifications\n\nPush notifications provide a mechanism to lazily retrieve information about an account in order to avoid the need for API clients to create polling infrastructure.\n\nRather than having to frequently check for changes, instead we inform you when changes have occurred so that you can retrieve them.\n\nThis enables you to keep your data as fresh as possible whilst using minimal computing resources.\n\nTo enable push notifications just fill in \"Notification Url\" field in [Org Settings > Integrations > API](https://app.circa.co/settings/integrations/api) page. Once the URL is specified, we will start sending push notifications for changes to events and contacts. Note that API requests do not trigger push notifications.\n\nThese will come in the form of `POST` requests with a `Content-Type` of `application/json`. Request body example:\n\n```\n{\n  \"changed_at\": \"2020-05-15T09:37:11Z\",\n  \"change_log\": [\n    {\n      \"action\": \"create\",\n      \"resource_id\": \"Q29udGFjdC0x\",\n      \"resource_type\": \"Contact\",\n      \"parent_type\": \"Event\",\n      \"parent_id\": \"RXZlbnQtNg\"\n    }\n  ]\n}\n\n```\n\n#### Request parameters\n\n| Attribute | Type | Description |\n| --- | --- | --- |\n| changed_at | Time | ISO 8601 in UTC, when the changes have been made |\n| change_log | Array\\[Change\\] | Array of objects containing change information |\n| Change.action | String | The type of a change. One of: `create`, `update`, `delete` |\n| Change.resource_id | String | Id of the resource that has been changed |\n| Change.resource_type | String | Type of the resource that has been changed. One of: `Event`, `Contact`, `EventContact`, `Company`, `Field`. We are sending `EventContact` resource_type when a Contact has been added to or removed from an Event |\n| Change.parent_id | String | Id of the parent resource. This field is optional and currently is being sent with only `EventContact` resource_type |\n| Change.parent_type | String | Type of the parent resource. Currently can be only `Event` |\n\n#### Expected response\n\nA successful response must have a response code in the `2xx` range and be returned within 5 seconds.  \nTherefore, anything that takes longer than 5 seconds to respond, or responds with a code not in the `2xx` range will be treated as if it has failed.\n\nWe will make 10 more attempts to send the push notification with 5 minute intervals. If no notifications succeed during this period then it is assumed that the URL is no longer valid and no further push notifications will be sent. To continue receiving push notifications go to [Org Settings > Integrations > API](https://app.circa.co/settings/integrations/api) page and provide a new \"Notification Url\" or hit \"Refresh\" button.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"11435283","team":1043690,"collectionId":"2e9ed469-2710-4af3-88b0-d6b5f9048988","publishedId":"SztA8pFi","public":true,"publicUrl":"https://docs.circa.co","privateUrl":"https://go.postman.co/documentation/11435283-2e9ed469-2710-4af3-88b0-d6b5f9048988","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"5E5CB7"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2020-10-31T10:22:46.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Production","id":"e3e4861b-9d44-4058-b970-e8fbbcf010ae","owner":"11435283","values":[{"key":"api_path","value":"https://app.circa.co/api/v1","enabled":true},{"key":"api_secret_key","value":"","enabled":true},{"key":"fieldId","value":"Q3VzdG9tRmllbGRUeXBlLTE","enabled":true},{"key":"teamId","value":"VGVhbS0z","enabled":true},{"key":"eventId","value":"RXZlbnQtNQ","enabled":true},{"key":"contactId","value":"Q29udGFjdC0x","enabled":true},{"key":"companyId","value":"Q29tcGFueS0xNA","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/43e958256d7e17a4c085350f6ccf94b359c59c849a65e7246ff1d25ca98543ab","favicon":"https://res.cloudinary.com/postman/image/upload/v1608887437/team/mjzyusdipkzi0khgb5zx.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Production","value":"11435283-e3e4861b-9d44-4058-b970-e8fbbcf010ae"}],"canonicalUrl":"https://docs.circa.co/view/metadata/SztA8pFi"}