The section will give an introduction to the overall structure of the API. The API uses a REST-like structure, while not adhering strictly to the standard, it uses HTTP verbs, status codes and URL paths in a way that should be familiar to those familiar with REST.
\nThe API is JSON based, and JSON is used in request bodies and responses. The responses format is described in greater details below.
\nAll requests made to the Accutics open API, must be authenticated using a JWT based bearer token set in the Authorization header. The token must belong to an API user profile. Contact support to create an API user and to get instructions on how to acquire the access token corresponding to that user.
The permissions granted when using the token are controlled by the project and accounts the API user is added to and the roles given to it. This is managed in the Accutics Platform.
\nAll successful responses follow a common format, which will be described here. Successful requests will have a 2xx HTTP status code. See details about the response contents and status codes for specific requests in the appropriate sections of the this documentation.
All responses are JSON formatted and consist of two top-level attributes as shown in the example below:
\n{\n \"data\": [...],\n \"meta\": {...}\n}\n\nThe data property contains the requested data. For responses containing multiple entities the contents of the property will be an array of objects, i.e. when listing entities in \"index\" requests. Note that an index request which only contains one entity will still result in an array with a single entry. For requests that inherently returns a single entity, such as a \"show\" or \"create\" requests, the data attribute will contain an object.
The meta attribute contains meta data about the response, such as paging information. The exact content depends on the given request, however it always contains the endpoint property, which contains the name of the endpoint used.
Error responses follow a similar format to succesful responses. The meta property is also present here, while the data property is replaced by the error property.
The error property contains code (string) which can be used in conjunction with the HTTP status code, to determine the type of error. A list of general error codes is given below - error codes specific to individual requests are described in their respective sections.
The message property contains a human-readable description of the error that occurred.
\n\nNote that the message should not be used to programatically determine the nature of an error. The messages are subject to change between API versions or even within the same version - use the HTTP status code and
\ncodeproperty instead.
The data property contains a JSON object with data, which can be used to further investigate the cause of the error. The contents of the object varies between different requests and error codes.
{\n \"error\": {\n \"code\": \"...\",\n \"message\": \"...\",\n \"data\": {...}\n },\n \"meta\": {\n \"endpoint\": \"...\"\n }\n}\n\nThe table below documents general error responses that are not specific to certain requests.
\nThis section describes common options that can be used across various requests.
\nFor requests that list entities, paging can be used to request data page by page. The following query string parameter are supported:
\nRequests supporting pagination will have the pagination property in the meta property of the response. It contains the following information.
The property contains an object defined by the following JSON Schema.
\n{\n \"type\": \"object\",\n \"properties\": {\n \"first\": {\"type\": \"string\"},\n \"previous\": {\"type\": [\"string\", \"null\"]},\n \"current\": {\"type\": \"string\"},\n \"next\": {\"type\": [\"string\", \"null\"]},\n \"last\": {\"type\": \"string\"},\n \"items_per_page\": {\"type\": \"integer\"},\n \"total_items\": {\"type\": \"integer\"},\n \"page_param\": {\"type\": \"string\"},\n \"size_param\": {\"type\": \"string\"}\n }\n}\n\nThis endpoint retrieves a paginated list of options for a specific dataset within a project.
\nThe response for this request can be represented as a JSON schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": { \"type\": \"string\" },\n \"abbreviation\": { \"type\": \"string\" }\n }\n }\n },\n \"meta\": {\n \"type\": \"object\",\n \"properties\": {\n \"paging\": {\n \"type\": \"object\",\n \"properties\": {\n \"first\": { \"type\": \"string\" },\n \"previous\": { \"type\": \"string\" },\n \"current\": { \"type\": \"string\" },\n \"next\": { \"type\": \"string\" },\n \"last\": { \"type\": \"string\" },\n \"items_per_page\": { \"type\": \"integer\" },\n \"total_items\": { \"type\": \"integer\" },\n \"page_param\": { \"type\": \"string\" },\n \"size_param\": { \"type\": \"string\" }\n }\n },\n \"sorting\": { \"type\": \"array\" },\n \"endpoint\": { \"type\": \"string\" }\n }\n }\n }\n}\n\nIn addition to the common error codes
\n","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}},"urlObject":{"path":["projects",":project_id","datasets",":dataset_id","options"],"host":["https://api.accutics.com/standardize/v1"],"query":[],"variable":[{"description":{"content":"The ID (UUID) of the project the desired dataset belongs to.
\n","type":"text/plain"},"type":"any","value":"","key":"project_id"},{"description":{"content":"The ID (UUID) of the desired dataset.
\n","type":"text/plain"},"type":"any","value":"","key":"dataset_id"}]}},"response":[],"_postman_id":"f809fac5-e263-49e0-897b-4eab39aa739a"},{"name":"Get dataset options - Company","id":"ab3a6558-4523-4c62-83ef-3044b3d7e46e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.accutics.com/standardize/v1/divisions/:division_id/datasets/:dataset_id/options","description":"This endpoint retrieves a paginated list of options for a specific dataset within a company (division).
\nThe response for this request can be represented as a JSON schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": { \"type\": \"string\" },\n \"abbreviation\": { \"type\": \"string\" }\n }\n }\n },\n \"meta\": {\n \"type\": \"object\",\n \"properties\": {\n \"paging\": {\n \"type\": \"object\",\n \"properties\": {\n \"first\": { \"type\": \"string\" },\n \"previous\": { \"type\": \"string\" },\n \"current\": { \"type\": \"string\" },\n \"next\": { \"type\": \"string\" },\n \"last\": { \"type\": \"string\" },\n \"items_per_page\": { \"type\": \"integer\" },\n \"total_items\": { \"type\": \"integer\" },\n \"page_param\": { \"type\": \"string\" },\n \"size_param\": { \"type\": \"string\" }\n }\n },\n \"sorting\": { \"type\": \"array\" },\n \"endpoint\": { \"type\": \"string\" }\n }\n }\n }\n}\n\nIn addition to the common error codes
\n","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}},"urlObject":{"path":["divisions",":division_id","datasets",":dataset_id","options"],"host":["https://api.accutics.com/standardize/v1"],"query":[],"variable":[{"description":{"content":"The ID (UUID) of the company (division) the desired dataset belongs to.
\n","type":"text/plain"},"type":"any","value":"","key":"division_id"},{"description":{"content":"The ID (UUID) of the desired dataset.
\n","type":"text/plain"},"type":"any","value":"","key":"dataset_id"}]}},"response":[],"_postman_id":"ab3a6558-4523-4c62-83ef-3044b3d7e46e"}],"id":"7e793bf2-7307-4281-a1cc-20377a3e9e9a","description":"This section details the endpoints for fetching and manipulating dataset options. Datasets can be owned by either a project or a division, and depending on this ownership the path of the endpoints vary slightly.
\nWhen interacting with dataset options for datasets that belong to a project the path will include /project/:project_id/ while for datasets beloning to divisions the path will include /division/:division_id/.
For information about datasets and dataset values, see our knowledgebase article on the subject here.
\n","_postman_id":"7e793bf2-7307-4281-a1cc-20377a3e9e9a","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}}},{"name":"Allowed options","item":[{"name":"Get allowed options","id":"31b5e0b7-ad42-4580-80b2-715a9ffb4c25","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.accutics.com/standardize/v1/projects/:project_id/dependency_variants/:dependency_variant_id/allowed_options","description":"This endpoint retrieves a paginated list of options for a specific dataset within a company (division).
\nThe response for this request can be represented as a JSON schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"data\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"abbreviation\": {\n \"type\": [\"string\", \"null\"]\n },\n \"dictating_datasets\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"maxItems\": 3,\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"abbreviation\": {\n \"type\": [\"string\", \"null\"]\n }\n },\n \"required\": [\"value\"]\n }\n }\n },\n \"required\": [\"value\", \"dictating_datasets\"]\n }\n },\n \"meta\": {\n \"type\": \"object\",\n \"properties\": {\n \"paging\": {\n \"type\": \"object\",\n \"properties\": {\n \"first\": { \"type\": \"string\" },\n \"previous\": { \"type\": \"string\" },\n \"current\": { \"type\": \"string\" },\n \"next\": { \"type\": \"string\" },\n \"last\": { \"type\": \"string\" },\n \"items_per_page\": { \"type\": \"integer\" },\n \"total_items\": { \"type\": \"integer\" },\n \"page_param\": { \"type\": \"string\" },\n \"size_param\": { \"type\": \"string\" }\n }\n },\n \"sorting\": { \"type\": \"array\" },\n \"endpoint\": { \"type\": \"string\" }\n }\n }\n }\n}\n\nIn addition to the common error codes
\n","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}},"urlObject":{"path":["projects",":project_id","dependency_variants",":dependency_variant_id","allowed_options"],"host":["https://api.accutics.com/standardize/v1"],"query":[],"variable":[{"description":{"content":"The ID (UUID) of the project the desired dataset belongs to.
\n","type":"text/plain"},"type":"any","value":"","key":"project_id"},{"description":{"content":"The ID (UUID) of the desired dataset.
\n","type":"text/plain"},"type":"any","value":"","key":"dependency_variant_id"}]}},"response":[],"_postman_id":"31b5e0b7-ad42-4580-80b2-715a9ffb4c25"}],"id":"e1eeafd4-4bea-42e7-852b-c662a6df5b02","description":"This section details the endpoints for fetching the allowed options for a dataset dependency variant.
\nFor information about dependency variants and allowed options, see our knowledgebase article on the subject here.
\nThe data in the responses from this endpoint lists the values from the corresponding dataset, along with the values from the dictating dataset(s) defined in the dependency variant. If the same value is allowed for multiple combinations of values from the dictating datasets, it will appear multiple times in the response (possibly on different pages). The values from the dictating datasets are listed in the dictating_datasets array for each value in the order in which the dictating datasets are set in the dependency variant.
Consider the following example. A project contains a dataset containing marketing channels (Social Paid, Social Organic, Search, etc.) called \"Channels\" and a dataset containing sources (Facebook, Google Ads, etc.) called Sources. The \"Sources\" dataset has a depencency variant with a single dependency - the \"Channels\" dataset.
\nThe \"Facebook\" source is allowed when the channel is \"Social Paid\" or \"Social Organic\" so it appears twice in the response.
\n{\n \"data\": [\n {\n \"value\": \"Facebook\", // First occurence.\n \"abbreviation\": \"fb\",\n \"dictating_datasets\": [\n {\n \"value\": \"Social Paid\",\n \"abbreviation\": \"socp\"\n }\n ]\n },\n {\n \"value\": \"Facebook\", // Second occurence.\n \"abbreviation\": \"fb\",\n \"dictating_datasets\": [\n {\n \"value\": \"Social Organic\",\n \"abbreviation\": \"soco\"\n }\n ]\n },\n {\n \"value\": \"Google Ads\",\n \"abbreviation\": \"ga\",\n \"dictating_datasets\": [\n {\n \"value\": \"Search\",\n \"abbreviation\": \"search\"\n }\n ]\n }\n ],\n \"meta\": [...]\n}\n\nThis endpoint is used to create a new record on a specific project.
\n\n\nLimitations
\n
An input field can have a default value which is a predefined value that is visible in the UI. Those are not predefined when sending requests through the API, meaning that any non-specified fields will be considered null.
The contents of the request body must be customized for the given project to include the inputs configured on the project. Inputs are set using their IDs as key and desired value, as shown in the example below. All mandatory fields must be set.
\n{\n \"data\": {\n \"b13022d2-6f57-4cda-846f-713e4f8769c7\": \"https://www.example.com\",\n \"d952013e-2545-42e0-b327-a5c467563baf\": \"Paid Search\", \n \"37ff53d1-3820-4979-8081-7dcc8b781789\": \"Google Ads\",\n \"f14a8d20-2e56-458a-b6dc-d8ec2adae6ce\": \"My Campaign\"\n }\n}\n\nThe value provided depends on the type of input field. The the example above have four inputs with the following types, URL, Dropdown, Dropdown and Text. All available input field types are described in our knowledgebase here.
\n{ \n \"data\": {...},\n \"meta\": { \n \"validation_rules_already_enforced\": true\n }\n}\n\nIn addition to the common error codes
\n","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}},"urlObject":{"path":["projects",":project_id","records"],"host":["https://api.accutics.com/standardize/v1"],"query":[],"variable":[{"description":{"content":"The ID (UUID) of the project the record will be created in.
\n","type":"text/plain"},"type":"any","value":"","key":"project_id"}]}},"response":[],"_postman_id":"8856f60c-4bc7-4ed1-b26f-8386c0355cf9"},{"name":"Update record","id":"dc2407cf-abc4-465f-aa40-12624a1d91e1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://api.accutics.com/standardize/v1/projects/:project_id/records/:record_id","description":"This endpoint is used to update an existing record on the specified project.
\nNote, that updating records on a project may not be possible or require certain permissions, depending on the configuration of the project. See the knowledgebase article on the subject here.
\nIndividual input fields could also have editing disabled. In such cases, the input field must either be omitted from the request, or the value must be the same as the original.
\nValidation errors could also occur on input field that are not included in the request if the configuration has changed since the record was created in a way that makes the original value invalid.
\nThe structure of the request is the same as for the \"Create record\" endpoint, with the exception, that only the inputs provided in the request will be modified - all inputs not specied in the request will maintain their original values. Note that depending on the configuration of the project, changing the value of one input field could make another invalid, even if it is not specified in the request.
\nTo \"unset\" the value of an optional input field, specify the input field key, but set the value to null as shown in the example below.
{\n \"data\": {\n \"b13022d2-6f57-4cda-846f-713e4f8769c7\": null\n }\n}\n\n{ \n \"data\": {...},\n \"meta\": { \n \"validation_rules_already_enforced\": true\n }\n}\n\nIn addition to the common error codes
\n","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}},"urlObject":{"path":["projects",":project_id","records",":record_id"],"host":["https://api.accutics.com/standardize/v1"],"query":[],"variable":[{"description":{"content":"The ID (UUID) of the project the project the record belongs to.
\n","type":"text/plain"},"type":"any","value":"","key":"project_id"},{"description":{"content":"The ID (UUID) of the record to be updated.
\n","type":"text/plain"},"type":"any","value":"","key":"record_id"}]}},"response":[],"_postman_id":"dc2407cf-abc4-465f-aa40-12624a1d91e1"}],"id":"f3e5caf9-c074-4e57-b50c-38e59d250444","_postman_id":"f3e5caf9-c074-4e57-b50c-38e59d250444","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[]},"isInherited":true,"source":{"_postman_id":"c25df722-32b0-471f-aa12-a01f0a8b998d","id":"c25df722-32b0-471f-aa12-a01f0a8b998d","name":"Accutics Open API - Documentation","type":"collection"}}}],"auth":{"type":"bearer","bearer":{"basicConfig":[]}},"event":[{"listen":"prerequest","script":{"id":"f716f1c4-7731-4298-8344-02fbe00c2d11","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"99ba00d0-972f-4304-a32a-089e9cc9aafa","type":"text/javascript","packages":{},"exec":[""]}}],"variable":[{"key":"api_version","value":"v1","type":"string"},{"key":"tcc_domain","value":"api.accutics.com","type":"string"},{"key":"tcc_base_url","value":"https://api.accutics.com/standardize/v1","type":"string"}]}