One single API to push and pull data from multiple connectors.

Introduction

Welcome to the ATS API.

You can use this API structure to access API endpoints.

The base URL for all API requests is https://api.chattechnologies.com

Headers

Custom headers that are expected as part of the request.

Name	Type	Required	Description

Name	Type	Required	Description
ct-consumer-id	String	Yes	The id of the customer stored inside CT. This can be a user id, account id, device id or whatever entity that can have integration within your application.
ct-service-id	String	No	Describe the service you want to call (e.g., chatrecruit). Only needed when a customer has activated multiple integrations.
ct-raw	Boolean	No	Include raw response. Mostly used for debugging purposes.
ct-app-id	String	Yes	The application id
Authorization	String	Yes	Bearer API KEY

Authorization

You can interact with the API through the authorization methods below.

To use API you have to sign up and get your own API key.

Authenticate your API requests by including your live secret API key in the request header.

Bearer authorization header: Authorization: Bearer <your-ct-api-key>
Application id header: ct-app-id: <your-ct-app-id>

Do not share or include your secret API keys on client side code. Your API keys carry significant privileges. Please ensure to keep them 100% secure and be sure to not share your secret API keys in areas that are publicly accessible like GitHub.

Learn how to set the Authorization header inside Postman API authentication and authorization in Postman | Postman Learning Center

Pagination

API resources have support for bulk retrieval via list APIs. CT API uses cursor-based pagination via the optional cursor and limit parameters.

To fetch the first page of results, call the list API without a cursor parameter. Afterwards you can fetch subsequent pages by providing a cursor parameter. You will find the next cursor in the response body in metadata.cursors.next. If metadata.cursors.next is null you're at the end of the list.

Query Parameters

Name	Type	Required	Description

Name	Type	Required	Description
cursor	String	No	Cursor to start from. You can find cursors for next & previous pages in the metadata.cursors property of the response.
limit	Number	No	Number of results to return. Minimum 1, Maximum 300, Default 50

Errors

The API returns standard HTTP response codes to indicate success or failure of the API requests. For errors, we also return a customized error message inside the JSON response. You can see the returned HTTP status codes below.

Code	Title	Description

Code	Title	Description
200	OK	The request message has been successfully processed, and it has produced a response. The response message varies, depending on the request method and the requested data.
201	Created	The request has been fulfilled and has resulted in one or more new resources being created.
204	No Content	The server has successfully fulfilled the request and that there is no additional content to send in the response payload body.
400	Bad Request	The receiving server cannot understand the request because of malformed syntax. Do not repeat the request without first modifying it; check the request for errors, fix them and then retry the request.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource.
402	Payment Required	Subscription data is incomplete or out of date. You'll need to provide payment details to continue.
403	Forbidden	You do not have the appropriate user rights to access the request. Do not repeat the request.
404	Not Found	The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
409	Conflict	The request could not be completed due to a conflict with the current state of the target resource.
422	Unprocessable Entity	The server understands the content type of the request entity, and the syntax of the request entity is correct but was unable to process the contained instructions.
429	Too Many Requests	You sent too many requests in a given amount of time ("rate limit"). Try again later
5xx	Server Errors	Something went wrong with the Unify API. These errors are logged on our side. You can contact our team to resolve the issue.

API Styles and data formats

REST API

The API is organized around REST, providing simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like GET, PUT, POST, and DELETE and standard status codes. JSON is returned by all API responses, including errors. In all API requests, you must set the content-type HTTP header to application/json. All API requests must be made over HTTPS. Calls made over HTTP will fail.

Available HTTP methods

The Chat Technologies API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your web application cannot do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

POST /messages
GET /messages
GET /messages/{messageId}
PATCH /messages/{messageId}
DELETE /messages/{messageId}

Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise. For some endpoints and use cases we divert from REST to provide a better developer experience.

Schema

All API requests and response bodies adhere to a common JSON format representing individual items, collections of items, links to related items and additional meta data.

Support

If you have problems or need help with your case, you can always reach out to our Support.

Companies & Candidates Examples

Please note all of these formats / values are customizable based on your integration needs. Below are just request and response examples.

curl --location 'https://api.chattechnologies.com/company' \
--header 'Authorization: Token token=.......................' \

REQUEST 
curl --location --request PATCH 'https://api.chattechnologies.com/company' \
--header 'Authorization: Token token=..........................' \
--header 'Content-Type: application/vnd.api+json' \
--data '{
    "data": {
        "type": "companies",
        "id": "<insert your company uuid>",
        "attributes": {
            "name": "Acme Corp"
        },
        "relationships": {
            "manager": {
                "data": {
                    "type": "users",
                    "id": "1"
                }
            }
        }
    }
}'

RESPONSE
{
  "data": {
    "id": "ZPX-868y8",
    "type": "companies",
    "links": {
      "self": "https://api.chattechnoloties.localhost/companies/ZPX-868y8"
    },
    "attributes": {
      "locale": "en",
      "website": "",
      "name": "Acme Corp"
    },
    "relationships": {
      "manager": {
        "links": {
          "self": "https://api.chattechnologies.localhost/companies/ZPX-868y8/relationships/manager",
          "related": "https://api.chattechnologies.localhost/companies/ZPX-868y8/manager"
        }
      }
    }
  }
}

Response
{
  "data": {
    "id": "447",
    "type": "candidates",
    "links": {
      "self": "https://api.chattechnologies.localhost/candidates/447"
    },
    "attributes": {
      "connected": false,
      "created-at": "2020-12-15T10:36:53.370+01:00",
      "email": "jonas@example.com",
      "facebook-id": null,
      "first-name": "Jonas",
      "internal": false,
      "last-name": "Brusman",
      "linkedin-uid": null,
      "linkedin-url": null,
      "original-resume": null,
      "phone": null,
      "picture": null,
      "pitch": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "referring-site": null,
      "referring-url": null,
      "referred": false,
      "resume": null,
      "sourced": false,
      "unsubscribed": false,
      "updated-at": "2020-12-15T10:36:53.370+01:00",
      "facebook-profile": null,
      "linkedin-profile": null,
      "tags": []
    },
    "relationships": {
      "activities": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/activities",
          "related": "https://api.chattechnologies.localhost/candidates/447/activities"
        }
      },
      "department": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/department",
          "related": "https://api.chattechnologies.localhost/candidates/447/department"
        }
      },
      "role": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/role",
          "related": "https://api.chattechnologies.localhost/candidates/447/role"
        }
      },
      "regions": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/regions",
          "related": "https://api.chattechnologies.localhost/candidates/447/regions"
        }
      },
      "job-applications": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/job-applications",
          "related": "https://api.chattechnologies.localhost/candidates/447/job-applications"
        }
      },
      "questions": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/questions",
          "related": "https://api.chattechnologies.localhost/candidates/447/questions"
        }
      },
      "answers": {
        "links": {
          "self": "https://api.chattechnologies.localhost/v1/candidates/447/relationships/answers",
          "related": "https://api.chattechnologies.localhost/candidates/447/answers"
        }
      },
      "locations": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/locations",
          "related": "https://api.chattechnologies.localhost/candidates/447/locations"
        }
      },
      "uploads": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/uploads",
          "related": "https://api.chattechnologies.localhost/candidates/447/uploads"
        }
      },
      "custom-field-values": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/custom-field-values",
          "related": "https://api.chattechnologies.localhost/candidates/447/custom-field-values"
        }
      },
      "partner-results": {
        "links": {
          "self": "https://api.chattechnologies.localhost/candidates/447/relationships/partner-results",
          "related": "https://api.chattechnologies.localhost/candidates/447/partner-results"
        }
      }
    }
  }
}

Example Datapoints

Changes

Required scope

Admin

Attributes

Attribute	Type	Description

Attribute	Type	Description
code	string	Activity type
created-at	date
data	string	Json string with activity data, like note text, todo value etc.

Relations

Relation	Description

Relation	Description
candidate	Candidate which the activity concerns
job	Job which the activity concerns
user	User who creates the activity

Candidates

Attribute	Type	Description

Attribute	Type	Description
connected	boolean
consent-future-jobs-at	date	Read only, the date candidate gave consent for contacting about future jobs.
consent-given-future-jobs	boolean	Write only, True if candidate gave consent for contacting about future jobs.
created-at	date
updated-at	date
email	string	Email to candidate. Always unique.
facebook-id	string	User id if connected with Facebook
facebook-profile	string	Read only, html version of Facebook profile
first-name	string
internal	boolean
last-name	string
linkedin-profile	string	Read only, html version of LinkedIn profile
linkedin-uid	string	User id if connected with LinkedIn
linkedin-url	string	URL to LinkedIn profile
merge	boolean	Write only True if the attributes should be merged with an existing candidate, matched by email address. To merge with a `sourced` candidate, the undocumented attribute `sourced_at` needs to be in the payload.
original-resume	string	Read only Signed URL to original version of resume, valid for 30 seconds.
phone	string
picture	string	Url to candidate picture
pitch	string	140 character pitch
referring-site	string	Read only, friendly name parsed from referring-url (i.e. Facebook, Indeed etc)
referring-url	string
referred	boolean	Read only True if added by an employee.
resume	string	Signed URL to pdf-version of resume, valid for 30 seconds. When creating a candidate, this should be a publicly available URL to a document.
sourced	boolean	True if added by a recruiter without applying
set-consent-expiration	boolean	Write only True if candidate have given their consent for you to store their personal details. Will set an expiration period according to your data retention policy.
tags	array
unsubscribed	boolean	If true no new job notifications are sent
send-welcome-message	boolean	Create only, set to true if you want to send the "Welcome to connect" email to the candidate. Default: false

Companies

Attributes

Attribute	Type	Description

Attribute	Type	Description
name	string	Company name
locale	string	Career site language. Possible values: ar, cs, da, de, en, es, et, fi, fil, fr, hu, it, ja, ko, lv, ms, nl, no, pl, pt, ro, ru, sv, th, tr, zh-CN
website	string	Company website URL

Relations

Relation	Description

Relation	Description
manager	The Admin user who is assigned `manager` for this company. Used as default sender of some emails, and as fallback where a user is always needed.

Departments

Attributes

Attribute	Type	Description

Attribute	Type	Description
name	string	The departmen's name

Relations

Relation	Description

Relation	Description
roles	The department's roles
teams	The teams this department is part of

{
  "data": {
    "id": "1",
    "type": "departments",
    "links": {
      "self": "https://api.chattechnologies.localhost/departments/1"
    },
    "attributes": {
      "name": "Product Development"
    },
    "relationships": {
      "roles": {
        "links": {
          "self": "https://api.chattechnologies.localhost/departments/1/relationships/roles",
          "related": "https://api.chattechnologies.localhost/departments/1/roles"
        }
      },
      "teams": {
        "links": {
          "self": "https://api.chattechnologies.localhost/departments/1/relationships/teams",
          "related": "https://api.chattechnologies.localhost/departments/1/teams"
        }
      }
    }
  },
  "meta": {
    "texts": {
      "name-singular": "department",
      "name-plural": "departments",
      "all": "All departments"
    }
  }
}

ROLES

Attributes

Attribute	Type	Description

Attribute	Type	Description
name	string	The name of the role

Relations

Relation	Description

Relation	Description
department	Parent Department
teams	The teams this role is part of