Version 3 of the CATS API s a complete redesign and contains many changes from the previous version.
Feedback and questions can be left on our community support forums.
The host for API requests is https://api.catsone.com/v3
.
All API requests must be made over HTTPS. HTTP is not supported.
To access the API, you will need a v3 API key. You can create an API key from the Administration settings page in CATS. Note that Transaction Codes for the previous version of the API will not work.
To authenticate, add an Authorization
header to your requests that contains a value in the form
Token <Your API Key>
.
Example header:
Authorization: Token <Your API Key>
All requests are formatted as JSON. Only JSON request bodies are accepted, and response bodies are always JSON.
You should specify a Content-Type
header with a value of application/json
.
Content-Type: application/json
This header is recommended, though not strictly required as application/json
will always be the default.
All timestamps and dates (both those sent in requests and those returned in responses) should be formatted according to RFC 3339.
Example:
2015-12-27T09:14:22-00:00
Country codes follow the ISO 3166 Alpha-2 format, both in the response and when country is being set via POST or PUT. This is a two letter format (US, NL, etc.) and information on the various codes can be found at the following links: iso.org or wikipedia
The CATS API adheres to the Hypertext Application Language specification, which is a simple format that provides a consistent and easy way to represent links between content and data structures.
Most response objects contain two keys that represent these links: _links
and _embedded
. The _links
key consists
of URI references to other resources that are associated with the object. The _embedded
key contains these links
embedded into the response object itself, so you can often retrieve the associated records without any extra API calls.
For example, a candidate
object may contain the following HAL items:
{
"id": 6465,
"first_name": "Sierra",
"last_name": "Orn",
"owner_id": 3587,
...
"_links": {
"self": {
"href": "/candidates/6465"
},
"custom_fields": {
"href": "/candidates/6465/custom_fields"
},
"owner": {
"href": "/users/3587"
},
"activities": {
"href": "/candidates/6465/activities"
}
}
}
These links point to the URIs to access the resources associated with this candidate.
Some associated resources may be included in the _embedded
key. For example:
"_embedded": {
"custom_fields": [
{
"id": 170911,
"value": "loma",
...
},
{...}
]
}
In this example, you can access the custom fields attached to the candidate without needing to make a separate API call.
All "List" methods take two pagination parameters: per_page
and page
.
per_page
signifies how many results to include on each page. It defaults to 25 and has a maximum of 100 on
all endpoints.
page
represents which page of results you wish to view and it always defaults to 1.
GET https://api.catsone.com/v3/candidates?per_page=100&page=4
Many resources share common functionality. For example, custom fields can be attached to a
candidate
, a contact
, a company
or a job
.
To represent associations with multiple types of records, some resources refer to a data_item
.
An example data_item
object:
{
"id": 3149,
"type": "candidate"
}
The id
field is the integer ID of a data item, and the type
field is the name of the data item type. The available
data item type names are: candidate
, contact
, company
and job
.
There are five endpoints you can run a filtered search on: Activities, Candidates, Companies, Contacts, and Jobs.
Filtering involves posting a json-formatted filter object. At the most basic level, this object simply has three keys:
filter
, field
, and value
. This will do a simple filter on a field based on a value. What fields can be filtered
on and what filters can be used on each filter are described on each of the endpoints themselves.
Beyond the simple filtering, we also offer the ability to chain filters together using boolean keywords such as and
,
or
, and not
. and
and or
always contain a list of objects (either a list of filters, a list of further booleans,
or some combination of the two), and not
always contains a filter.
The following are a few examples filter structure:
// Basic filter
{"field": "first_name", "filter": "exactly", "value": "Scott"}
// Basic AND filter
{
"and": [
{"field": "first_name", "filter": "exactly", "value": "Scott"},
{"field": "last_name", "filter": "exactly", "value": "Summers"}
]
}
// Basic OR filter
{
"or": [
{"field": "title", "filter": "contains", "value": "team leader"},
{"field": "title", "filter": "contains", "value": "squad leader"},
]
}
// Basic NOT filter
{
"not": {"field": "key_skills", "filter": "contains", "value": "subtlety"}
}
// All together
{
"and": [
{
"and": [
{"field": "first_name", "filter": "exactly", "value": "Scott"},
{"field": "last_name", "filter": "exactly", "value": "Summers"},
{
"not" : {"field": "middle_name", "filter": "exactly", "value": "Joseph"}
}
]
},
{
"or": [
{"field": "title", "filter": "contains", "value": "team leader"},
{"field": "title", "filter": "contains", "value": "squad leader"},
]
},
{
"not": {"field": "key_skills", "filter": "contains", "value": "subtlety"}
}
]
}
One final note: every filter allows for different values. Here they are for every filter:
`exactly` - string, int, or boolean depending on the type of field
`contains` - string
`between` - object containing the following
`gte` - the int or date string of the smaller end of the range (greater than or equal)
`lte` - the int or date string of the bigger end of the range (less than or equal)
`greater_than` - int or date string
`less_than` - int or date_string
`is_empty` - Value MUST be the boolean `true`, no other values are supported
`geo_distance` - object containing the following
`postal_code` - string
`distance` - int
`unit` - string, either `km` or `miles`
Custom fields can also be filtered on. The field
in this case is the id of the custom field, and it must be
an integer. Here are the allowed filters for each custom field type:
`text` - contains, exactly, is_empty
`number` - exactly, greater_than, less_than, between, is_empty
`date` - greater_than, less_than, between, is_empty,
`dropdown` - exactly, is_empty
`radio` - exactly, is_empty
`checkboxes` - exactly, is_empty
`checkbox` - exactly
`user` - exactly, is_empty
All calls to the CATS API are subject to a rate limit of 500 requests per hour. Rate limits are calculated on a rolling hourly basis.
Each request returns the following header information regarding rate limits:
X-Rate-Limit-Limit: <Total limit allowed>
X-Rate-Limit-Remaining: <Remaining requests allowed in the current period>
If a request exceeds the rate limit, a 429 Too Many Requests
error will be returned, and the response will return the
following additional header:
Retry-After: <Number of seconds until another request may be made>
{
"event": "candidate.created",
"candidate_id": 6089361,
"_links": {...},
"_embedded": {...}
}
The event
key will tell you which event has fired. Following that will be the id of the item that triggered the webhook. The name of this key will change depending on which type of item the webhook is about (candidate_id
, job_id
, etc.). Lastly, the _links
and _embedded
will have the link and the full contents of the the item itself, so you do not have to make any extra calls to fetch the item if you need it.
Note: Unlike all the API endpoints which are limited to 25 of each type of embed, webhooks will return up to 1000 of each type automatically. Thus, if you have 90 custom fields on a candidate, when a webhook for that candidate fires, it will return with all 90 of those custom fields embedded. This is to ensure that you get all the data you need without need to make any calls back to the API.
Status Change webhooks include more information than standard webhooks. Their fields are as follows:
{
"event": "pipeline.status_changed",
"pipeline_id": 664681364,
"previous_status_id": 1343445,
"new_status_id": 1262311,
"_links": {...},
"_embedded": {...}
}
As you can see, in addition to the normal event and id fields, both the previous status and the new status ids are included as well as also appearing in full in the embeds.
It should be noted that mass record updates will fire individual webhooks for all affected records. Because the UI does not put a cap on how many records you can update at once, the could result in a huge number of webhooks being set your way in a very short timeframe. If you believe the server or service you are using to accept webhooks from us cannot handle that bulk, we advise that you a make sure to do any mass actions with extreme caution.
Finally, we keep a tally of all 500 errors (or similar things like timeouts) encountered when trying to send a webhook to your specified url. If we receive a bad response 50 consecutive times within a 30 minute period, that specific webhook will be disabled and an email informing you of that will be sent.
View the changelog for updates and changes to the API.
required
string
The current page number of activities to return.
required
string
The number of activities to return per page.
curl -X GET \
https://api.catsone.com/v3/activities \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 102,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 4608,
"data_item": {
"id": 7451,
"type": "job"
},
"date": "2022-02-02T22:23:57.402Z",
"regarding_id": 2750,
"type": "call_lvm",
"notes": "Left voicemail.",
"annotation": "General",
"entered_by_id": 7304,
"date_created": "2022-04-04T00:35:24.661Z",
"date_modified": "2022-12-15T20:01:26.102Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the activity to return.
curl -X GET \
https://api.catsone.com/v3/activities/4608 \
-H 'authorization: Token <Your API Key>'
{
"id": 4608,
"data_item": {
"id": 7451,
"type": "job"
},
"date": "2022-02-02T22:23:57.402Z",
"regarding_id": 2750,
"type": "call_lvm",
"notes": "Left voicemail.",
"annotation": "General",
"entered_by_id": 7304,
"date_created": "2022-04-04T00:35:24.661Z",
"date_modified": "2022-12-15T20:01:26.102Z",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the activity to update.
required
string
One of the following activity types: email
, meeting
, call_talked
, call_lvm
, call_missed
, text_message
or other
.
number
The ID of the job order that this activity is regarding. Leave null
for a general activity.
string
string
The datetime the activity took place. If not specified it defaults to the current date and time.
curl -X PUT \
https://api.catsone.com/v3/activities/4799 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":9940,"notes":"Provident et repudiandae reiciendis quidem dolores exercitationem saepe aut.","date":"2022-04-14T05:25:50.723Z"}'
required
string
The ID of the activity to delete.
curl -X DELETE \
https://api.catsone.com/v3/activities/42 \
-H 'authorization: Token <Your API Key>'
required
string
The string to search within activities for.
required
string
The current page number of activities to return.
required
string
The number of activities to return per page.
curl -X GET \
https://api.catsone.com/v3/activities/search \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 102,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 4608,
"data_item": {
"id": 7451,
"type": "job"
},
"date": "2022-02-02T22:23:57.402Z",
"regarding_id": 2750,
"type": "call_lvm",
"notes": "Left voicemail.",
"annotation": "General",
"entered_by_id": 7304,
"date_created": "2022-04-04T00:35:24.661Z",
"date_modified": "2022-12-15T20:01:26.102Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This section describes the filters and fields that can be used to filter search results for this endpoint. The example given is the most simple way to pass a filter into the call. For a more in-depth explanation of boolean filtering, consult the section near the top of this page dealing with filtering.
The following are all the Activity fields that can currently be filtered on, and which filters can be used on each:
`id` - greater_than, less_than, between, exactly, is_empty
`data_item.id` - greater_than, less_than, between, exactly, is_empty
`data_item.type` - exactly, is_empty
`date - greater_than`, less_than, between, is_empty
`regarding_id` - greater_than, less_than, between, exactly, is_empty
`type` - exactly, is_empty
`notes` - contains, exactly, is_empty
`entered_by_id` - greater_than, less_than, between, exactly, is_empty
`date_created` - greater_than, less_than, between, is_empty
`date_modified` - greater_than, less_than, between, is_empty
required
string
The optional string to search within activities for.
required
string
The current page number of activities to return.
required
string
The number of activities to return per page.
required
string
The field to filter on. See the above list to determine which fields can be filtered.
required
string
The filter to use. See the above list to determine which fields allow what filters.
required
string
The value to filter by. Different filters take different value types (string, array, int). See the section in the introduction to see what values each filter accepts.
curl -X POST \
https://api.catsone.com/v3/activities/search \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
{
"count": 25,
"total": 102,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 4608,
"data_item": {
"id": 7451,
"type": "job"
},
"date": "2022-02-02T22:23:57.402Z",
"regarding_id": 2750,
"type": "call_lvm",
"notes": "Left voicemail.",
"annotation": "General",
"entered_by_id": 7304,
"date_created": "2022-04-04T00:35:24.661Z",
"date_modified": "2022-12-15T20:01:26.102Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the attachment to return.
curl -X GET \
https://api.catsone.com/v3/attachments/9981 \
-H 'authorization: Token <Your API Key>'
{
"id": 9981,
"filename": "readme.txt",
"is_resume": false,
"size": "",
"version": "",
"data_item": {
"id": 7554,
"type": "candidate"
}
}
required
string
The ID of the attachment to delete.
curl -X DELETE \
https://api.catsone.com/v3/attachments/5899 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the attachment to download.
curl -X GET \
https://api.catsone.com/v3/attachments/9981/download \
-H 'authorization: Token <Your API Key>'
Parses the supplied resume and returns a candidate object. No records are created or updated with this call. If you
want to create or update a candidate with the parsed data, make a second call with that returned candidate data,
usually a POST to /candidates
with the check_duplicate
flag set to true
.
curl -X POST \
https://api.catsone.com/v3/attachments/parse \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
{
"first_name": "Kamille",
"middle_name": "Mariam",
"last_name": "Brown",
"title": "Direct Research Technician",
"emails": {
"primary": "Jermaine26@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"phones": {
"home": "(853) 473-8570",
"cell": "(547) 979-6705",
"work": "(822) 332-7237"
},
"current_employer": "Bartoletti - Heaney",
"source": "Google"
}
required
string
The current page number of backups to return.
required
string
The number of backups to return per page.
curl -X GET \
https://api.catsone.com/v3/backups \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 618,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 3846,
"status": "expired",
"url": "https://myles.info",
"file_size": 294516033,
"started_by_id": 9871,
"date_created": "2022-01-07T19:05:41.119Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the backup to return.
curl -X GET \
https://api.catsone.com/v3/backups/4226 \
-H 'authorization: Token <Your API Key>'
{
"id": 3846,
"status": "expired",
"url": "https://myles.info",
"file_size": 294516033,
"started_by_id": 9871,
"date_created": "2022-01-07T19:05:41.119Z",
"_links": {...},
"_embedded": {...}
}
This will initiate the creation of a backup. As with all POST endpoints, a location header will be returned for the new backup item. You can query that endpoint to learn the status of the backup, and once it is completed to get its url.
boolean
Whether to include attachments in the backup or not. Running a backup without attachments can greatly speed up the backup time. Defaults to false.
boolean
Whether to include emails in the backup or not. Running a backup without emails can greatly speed up the backup time. Defaults to true.
curl -X POST \
https://api.catsone.com/v3/backups \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"include_attachments":false,"include_emails":true}'
required
string
The current page number of candidates to return.
required
string
The number of candidates to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 512,
"_links": {...},
"_embedded": {
"candidates": [
{
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the candidate to return.
curl -X GET \
https://api.catsone.com/v3/candidates/5299 \
-H 'authorization: Token <Your API Key>'
{
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
required
string
When this flag is set to true, if a duplicate record is found to the one being created, an error will be thrown instead of creating a duplicate record. Defaults to false.
required
string
string
required
string
string
The candidate's job title.
array
An array of email objects. Each email object should contain two keys: email
and is_primary
, as described here
[
{
"email": <email>,
"is_primary": "<is this the primary email?>"
}
]
array
An array of phone objects. Each phone object should contain three keys: number
, extension
, and type
, as described here
[
{
"number": <phone number with country code>,
"extension": "<optional extension>",
"type": "<phone number type>",
}
]
object
An object containing the address for the candidate with the following structure:
{
"street": "<street>",
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
array
string
string
string
string
The date the candidate is available for an opening.
string
string
boolean
string
string
string
number
The user id of the record owner
boolean
A flag indicating if the candidate is active.
boolean
A flag indicating if the candidate should be marked as hot. A hot candidate is highlighted in the candidates view.
string
The candidate's password if they are "registering". Registered candidate can be authenticated with /candidates/authorization
.
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this candidate.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
array
An array of work history objects. Each work history object should conform to the work history objects passed to the normal work history create endpoint
[
{
"title": "Engineer",
"employer": {
"linked": false,
"name": "<employer name>",
"location": {
"city": "<employer city>",
"state": "<employer state>"
}
},
"supervisor": {
"linked": false,
"name": "<supervisor name>",
"phone": "<supervisor phone number>"
},
"is_verified": true,
"is_current": false,
"start_date": "asdas",
"end_date": "asd",
"reason_for_leaving": "foo"
}
]
curl -X POST \
https://api.catsone.com/v3/candidates \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Kole","middle_name":"Liza Bull","last_name":"Howe","title":"International Quality Producer","emails":[{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}],"phones":[{"number":"+16124063451","extension":"8371","type":"Mobile"}],"address":{"street":"8291 Moshe Ways","city":"East Evieport","state":"Kansas","postal_code":"60044"},"country_code":"US","social_media_urls":[],"website":"http://maurice.biz","best_time_to_call":"","current_employer":"","date_available":"2019-04-04","current_pay":"","desired_pay":"","is_willing_to_relocate":false,"key_skills":"","notes":"","source":"Google","owner_id":8430,"is_active":true,"is_hot":true,"password":"aBDlWADe0q4ucs_","custom_fields":[{"id":8474,"value":"lorem"}],"work_history":[{"title":"Forward Integration Assistant","employer":{"linked":false,"name":"Satterfield, Franecki and Zulauf","location":{"city":"East Angeline","state":"IN"}},"supervisor":{"linked":false,"name":"Donny","phone":"(619) 861-7766"},"is_verified":true,"is_current":"false","start_date":"2022-05-14T00:03:00.437Z","end_date":"2022-02-12T21:40:21.527Z","reason_for_leaving":"Sunt et porro aut asperiores voluptatibus molestiae repellendus ut."}]}'
required
string
The ID of the candidate to update.
required
string
string
required
string
string
The candidate's job title.
object
An object containing the address for the candidate with the following structure:
{
"street": "<street>",
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
array
string
string
string
string
The date the candidate is available for an opening.
string
string
boolean
string
string
string
number
The user id of the record owner
boolean
A flag indicating if the candidate is active.
boolean
A flag indicating if the candidate should be marked as hot. A hot candidate is highlighted in the candidates view.
string
The candidate's password if they are "registering". Registered candidate can be authenticated with /candidates/authorization
.
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this candidate.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
curl -X PUT \
https://api.catsone.com/v3/candidates/6024 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Elian","middle_name":"Peyton Bull","last_name":"Kuvalis","title":"Internal Directives Orchestrator","address":{"street":"42272 Hoppe Views","city":"Legrosberg","state":"Iowa","postal_code":"01920-2431"},"country_code":"US","social_media_urls":[],"website":"","best_time_to_call":"","current_employer":"","date_available":"","current_pay":"","desired_pay":"","is_willing_to_relocate":false,"key_skills":"","notes":"","source":"Google","owner_id":8999,"is_active":false,"is_hot":false,"password":"3luHAeM_zaDt9EI","custom_fields":[{"id":8474,"value":"lorem"}]}'
required
string
The ID of the candidate to delete.
curl -X DELETE \
https://api.catsone.com/v3/candidates/8614 \
-H 'authorization: Token <Your API Key>'
Check if an email and password match an existing candidate. Returns the Candidate if authorized, or a 404 if not. You can use this endpoint to allow a user to "log in" and edit their contact data.
string
string
curl -X POST \
https://api.catsone.com/v3/candidates/authorization \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Brendan15@gmail.com","password":"oiSL7aMxfukU0ox"}'
{
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
}
List all pipelines associated with a candidate.
required
string
The ID of the candidate to return pipelines for.
required
string
The current page number of pipelines to return.
required
string
The number of pipelines to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/1449/pipelines \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 643,
"_links": {...},
"_embedded": {
"pipelines": [
{
"id": 3498,
"candidate_id": 982,
"job_id": 4487,
"rating": 0,
"workflow_id": 7843,
"status_id": 1048,
"date_created": "2022-03-06T02:02:58.136Z",
"date_modified": "2022-09-06T01:22:40.373Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the candidate to fetch tasks concerning.
required
string
The current page number of tasks to return.
required
string
The number of task items to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/5361/tasks \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 972,
"_links": {...},
"_embedded": {
"tasks": [
{
"id": 3609,
"data_item": {
"id": 2861,
"type": "candidate"
},
"entered_by_id": 7458,
"assigned_to_id": 144,
"description": "Deserunt laborum aperiam repellat et et illum aut accusamus officia.",
"priority": 2,
"date_due": "2022-02-23T15:37:27.130Z",
"is_completed": true,
"date_completed": "2022-05-26T13:07:31.452Z",
"date_created": "2022-11-13T12:03:05.548Z",
"date_updated": "2022-02-05T13:23:31.541Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The string to search within candidates for.
required
string
The current page number of candidates to return.
required
string
The number of candidates to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/search \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 512,
"_links": {...},
"_embedded": {
"candidates": [
{
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This section describes the filters and fields that can be used to filter search results for this endpoint. The example given is the most simple way to pass a filter into the call. For a more in-depth explanation of boolean filtering, consult the section near the top of this page dealing with filtering.
The following are all the Candidate fields that can currently be filtered on, and which filters can be used on each:
`id` - greater_than, less_than, between, exactly, is_empty
`first_name` - contains, exactly, is_empty
`middle_name` - contains, exactly, is_empty
`last_name` - contains, exactly, is_empty
`title` - contains, exactly, is_empty
`emails.primary` - contains, exactly, is_empty
`emails.secondary` - contains, exactly, is_empty
`address.street` - contains, exactly, is_empty
`address.city` - contains, exactly, is_empty
`address.state` - contains, exactly, is_empty
`address.postal_code` - geo_distance, contains, exactly, is_empty
`country_code` - contains, exactly, is_empty
`phones.home` - contains, exactly, is_empty
`phones.cell` - contains, exactly, is_empty
`phones.work` - contains, exactly, is_empty
`best_time_to_call` - contains, exactly, is_empty
`current_employer` - contains, exactly, is_empty
`date_available` - greater_than, less_than, between, is_empty
`current_pay` - contains, exactly, is_empty
`desired_pay` - contains, exactly, is_empty
`is_willing_to_relocate` - exactly, is_empty
`key_skills` - contains, exactly, is_empty
`notes` - contains, exactly, is_empty
`is_hot` - exactly, is_empty
`contact_id` - greater_than, less_than, between, exactly, is_empty
`owner_id` - greater_than, less_than, between, exactly, is_empty
`entered_by_id` - greater_than, less_than, between, exactly, is_empty
`date_created` - greater_than, less_than, between, is_empty
`date_modified` - greater_than, less_than, between, is_empty
`resumes` - contains
`resumes.name` - contains, exactly, is_empty
required
string
The optional string to search within candidates for.
required
string
The current page number of candidates to return.
required
string
The number of candidates to return per page.
required
string
The field to filter on. See the above list to determine which fields can be filtered.
required
string
The filter to use. See the above list to determine which fields allow what filters.
required
string
The value to filter by. Different filters take different value types (string, array, int). See the section in the introduction to see what values each filter accepts.
curl -X POST \
https://api.catsone.com/v3/candidates/search \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
{
"count": 25,
"total": 512,
"_links": {...},
"_embedded": {
"candidates": [
{
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The candidate to return phones for.
required
string
The current page number of phones to return.
required
string
The number of phones to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/8003/phones \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 822,
"_links": {...},
"_embedded": {
"phones": [
{
"id": 3408,
"number": "623.714.4685 x4297",
"extension": "612",
"type": "Mobile",
"date_created": "2022-07-05T02:56:11.498Z",
"date_modified": "2022-07-21T16:20:35.365Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The candidate to return the phone for.
required
string
The ID of the phone to return.
curl -X GET \
https://api.catsone.com/v3/candidates/2217/phones/2169 \
-H 'authorization: Token <Your API Key>'
{
"id": 3408,
"number": "623.714.4685 x4297",
"extension": "612",
"type": "Mobile",
"date_created": "2022-07-05T02:56:11.498Z",
"date_modified": "2022-07-21T16:20:35.365Z",
"_links": {...},
"_embedded": {...}
}
required
string
The candidate to create the phone for.
required
string
This number MUST begin with the country code. It will not be parsed correctly otherwise.
string
required
string
One of mobile
, home
, work
, fax
, main
, or other
.
curl -X POST \
https://api.catsone.com/v3/candidates/5182/phones \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
required
string
The candidate to update the phone for.
required
string
The ID of the phone to update.
required
string
This number MUST begin with the country code. It will not be parsed correctly otherwise.
string
required
string
One of mobile
, home
, work
, fax
, main
, or other
.
curl -X PUT \
https://api.catsone.com/v3/candidates/6247/phones/7526 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
required
string
The candidate to delete the phone from.
required
string
The ID of the phone to delete.
curl -X DELETE \
https://api.catsone.com/v3/candidates/1167/phones/6675 \
-H 'authorization: Token <Your API Key>'
required
string
The candidate to return emails for.
required
string
The current page number of emails to return.
required
string
The number of emails to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/464/emails \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 957,
"_links": {...},
"_embedded": {
"emails": [
{
"id": 6754,
"email": "Virginie7@hotmail.com",
"is_primary": true,
"date_created": "2022-06-24T23:25:26.606Z",
"date_modified": "2022-02-27T05:37:10.167Z",
"_links": {...}
},
{...}
]
}
}
required
string
The candidate to return the email for.
required
string
The ID of the email to return.
curl -X GET \
https://api.catsone.com/v3/candidates/649/emails/3514 \
-H 'authorization: Token <Your API Key>'
{
"id": 6754,
"email": "Virginie7@hotmail.com",
"is_primary": true,
"date_created": "2022-06-24T23:25:26.606Z",
"date_modified": "2022-02-27T05:37:10.167Z",
"_links": {...}
}
required
string
The candidate to create the email for.
required
string
boolean
If a record has any number of emails, exactly one of them must be marked as primary.
curl -X POST \
https://api.catsone.com/v3/candidates/9549/emails \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}'
required
string
The candidate to update the email for.
required
string
The ID of the email to update.
required
string
boolean
If a record has any number of emails, exactly one of them must be marked as primary.
curl -X PUT \
https://api.catsone.com/v3/candidates/4533/emails/6414 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}'
required
string
The candidate to delete the email from.
required
string
The ID of the email to delete.
curl -X DELETE \
https://api.catsone.com/v3/candidates/973/emails/8347 \
-H 'authorization: Token <Your API Key>'
List all custom field definitions associated with the candidate data item type. Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
, or number
.
required
string
The current page number of custom field definitions to return.
required
string
The number of custom field definitions to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 845,
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 832,
"data_item_type": "candidate",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
},
{...}
]
}
}
Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
, or number
.
required
string
The ID of the custom field definition to return.
curl -X GET \
https://api.catsone.com/v3/candidates/custom_fields/832 \
-H 'authorization: Token <Your API Key>'
{
"id": 832,
"data_item_type": "candidate",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
}
List all custom field values associated with a candidate. This returns the values of all custom fields for the candidate
data item type for a single candidate.
required
string
The ID of the candidate to return custom fields for.
required
string
The current page number of custom fields to return.
required
string
The number of custom fields to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/1410/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": "764",
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Get a single custom field value for a candidate.
required
string
The ID of the candidate that the custom field belongs to.
required
string
The ID of the custom field to return.
curl -X GET \
https://api.catsone.com/v3/candidates/8339/custom_fields/2076 \
-H 'authorization: Token <Your API Key>'
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the candidate that the custom field belongs to.
required
string
The ID of the custom field to update.
required
string
curl -X PUT \
https://api.catsone.com/v3/candidates/3936/custom_fields/9426 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"fredy"}'
List all activities associated with a candidate.
required
string
The ID of the candidate to return activities for.
required
string
The current page number of activities to return.
required
string
The number of activities to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/3890/activities \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 463,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 404,
"data_item": {
"id": 2861,
"type": "candidate"
},
"date_created": "2022-06-19T14:41:54.371Z",
"regarding_id": 4676,
"type": "other",
"notes": "Added candidate to pipeline.",
"annotation": "General",
"entered_by_id": 7046,
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Log an activity against a candidate.
required
string
The ID of the candidate to create an activity for.
required
string
One of the following activity types: email
, meeting
, call_talked
, call_lvm
, call_missed
, text_message
or other
.
number
The ID of the job order that this activity is regarding. Leave null
for a general activity.
string
string
The datetime the activity took place. If not specified it defaults to the current date and time.
curl -X POST \
https://api.catsone.com/v3/candidates/6624/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":9940,"notes":"Provident et repudiandae reiciendis quidem dolores exercitationem saepe aut.","date":"2022-04-14T05:25:50.723Z"}'
required
string
The ID of the candidate to return attachments for.
required
string
The current page number of attachments to return.
required
string
The number of attachments to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/798/attachments \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 325,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 9981,
"filename": "readme.txt",
"is_resume": false,
"size": "",
"version": "",
"data_item": {
"id": 7554,
"type": "candidate"
}
},
{...}
]
}
}
required
string
The ID of the candidate that the attachment is being attached to.
required
string
The name to save the file being uploaded as.
curl -X POST \
https://api.catsone.com/v3/candidates/7785/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Resumes are attachments that are marked as a resume in a candidate's profile and are indexed for boolean keyword search. They are otherwise identical to standard attachments.
required
string
The ID of the candidate that the resume is being attached to.
required
string
The name to save the file being uploaded as.
curl -X POST \
https://api.catsone.com/v3/candidates/190/resumes \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
required
string
The ID of the candidate to fetch work history for.
required
string
The current page number of work history to return.
required
string
The number of work history items to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/7207/work_history \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 141,
"_links": {...},
"_embedded": {
"work_history": [
{
"id": 5299,
"title": "Principal Configuration Assistant",
"candidate_id": 8736,
"employer": {
"linked": false,
"name": "Grant Group",
"location": {
"city": "Lake Simeonport",
"state": "NV"
}
},
"supervisor": {
"linked": false,
"name": "Octavia",
"phone": "(400) 379-2500"
},
"is_verified": false,
"is_current": false,
"start_date": "2022-02-20T22:28:24.180Z",
"end_date": "2022-03-19T05:10:17.283Z",
"reason_for_leaving": "Voluptatem tenetur enim nostrum dolores laborum unde aut repellat dignissimos."
},
{...}
]
}
}
required
string
The ID of the work history to return.
curl -X GET \
https://api.catsone.com/v3/candidates/work_history/9528 \
-H 'authorization: Token <Your API Key>'
{
"id": 5299,
"title": "Principal Configuration Assistant",
"candidate_id": 8736,
"employer": {
"linked": false,
"name": "Grant Group",
"location": {
"city": "Lake Simeonport",
"state": "NV"
}
},
"supervisor": {
"linked": false,
"name": "Octavia",
"phone": "(400) 379-2500"
},
"is_verified": false,
"is_current": false,
"start_date": "2022-02-20T22:28:24.180Z",
"end_date": "2022-03-19T05:10:17.283Z",
"reason_for_leaving": "Voluptatem tenetur enim nostrum dolores laborum unde aut repellat dignissimos."
}
required
string
The ID of the candidate to create work history for.
required
string
required
object
An object containing the employer information for a work history item with one of the following structures:
{
"linked": false,
"name": "<employer name>",
"location": {
"city": "<employer city>",
"state": "<employer state>"
}
}
or
{
"linked": true,
"company_id": 465
}
Both linked
and name
are required fields within the first object, and linked
and company_id
are required in the second object.
object
An object containing the supervisor information for a work history item with one of the following structures:
{
"linked": false,
"name": "<supervisor name>",
"phone": "<supervisor phone number>"
}
or
{
"linked": true,
"contact_id": 6864
}
boolean
string
If this is set to true
, both end_date
and reason_for_leaving
will be ignored.
string
string
string
curl -X POST \
https://api.catsone.com/v3/candidates/9538/work_history \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Forward Integration Assistant","employer":{"linked":false,"name":"Satterfield, Franecki and Zulauf","location":{"city":"East Angeline","state":"IN"}},"supervisor":{"linked":false,"name":"Donny","phone":"(619) 861-7766"},"is_verified":true,"is_current":"false","start_date":"2022-05-14T00:03:00.437Z","end_date":"2022-02-12T21:40:21.527Z","reason_for_leaving":"Sunt et porro aut asperiores voluptatibus molestiae repellendus ut."}'
required
string
The ID of the work history to update.
required
string
required
object
An object containing the employer information for a work history item with one of the following structures:
{
"linked": false,
"name": "<employer name>",
"location": {
"city": "<employer city>",
"state": "<employer state>"
}
}
or
{
"linked": true,
"company_id": 465
}
Both linked
and name
are required fields within the first object, and linked
and company_id
are required in the second object.
object
An object containing the supervisor information for a work history item with one of the following structures:
{
"linked": false,
"name": "<supervisor name>",
"phone": "<supervisor phone number>"
}
or
{
"linked": true,
"contact_id": 6864
}
boolean
string
If this is set to true
, both end_date
and reason_for_leaving
will be ignored.
string
string
string
curl -X PUT \
https://api.catsone.com/v3/candidates/work_history/9413 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Forward Integration Assistant","employer":{"linked":false,"name":"Satterfield, Franecki and Zulauf","location":{"city":"East Angeline","state":"IN"}},"supervisor":{"linked":false,"name":"Donny","phone":"(619) 861-7766"},"is_verified":true,"is_current":"false","start_date":"2022-05-14T00:03:00.437Z","end_date":"2022-02-12T21:40:21.527Z","reason_for_leaving":"Sunt et porro aut asperiores voluptatibus molestiae repellendus ut."}'
required
string
The ID of the work history to delete.
curl -X DELETE \
https://api.catsone.com/v3/candidates/work_history/4328 \
-H 'authorization: Token <Your API Key>'
required
string
The current page number of lists to return.
required
string
The number of lists to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/lists \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 375,
"_links": {...},
"_embedded": {
"lists": [
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the candidate list to return.
curl -X GET \
https://api.catsone.com/v3/candidates/lists/6504 \
-H 'authorization: Token <Your API Key>'
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
}
required
string
string
curl -X POST \
https://api.catsone.com/v3/candidates/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"sint","notes":"Enim a explicabo dolor."}'
required
string
The ID of the candidate list to delete.
curl -X DELETE \
https://api.catsone.com/v3/candidates/lists/5608 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the candidate list to return items for.
required
string
The current page number of list items to return.
required
string
The number of list items to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/lists/2253/items \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 592,
"_links": {...},
"_embedded": {
"items": [
{
"id": 3236,
"date_created": "2022-12-06T10:36:49.476Z",
"candidate_id": 4908,
"_links": {...},
"_embedded": {
"candidate": {
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
}
}
},
{...}
]
}
}
required
string
The ID of the candidate list the item belongs to.
required
string
The ID of the candidate list item to return.
curl -X GET \
https://api.catsone.com/v3/candidates/lists/2980/items/2635 \
-H 'authorization: Token <Your API Key>'
{
"id": 3236,
"date_created": "2022-12-06T10:36:49.476Z",
"candidate_id": 4908,
"_links": {...},
"_embedded": {
"candidate": {
"id": 5299,
"first_name": "Olga",
"middle_name": "Randal",
"last_name": "Bayer",
"title": "Human Integration Consultant",
"emails": {
"primary": "Aidan_Steuber@hotmail.com",
"secondary": "Quentin12@hotmail.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"website": "http://colin.com",
"best_time_to_call": "After 5pm",
"current_employer": "Zieme LLC",
"date_available": "Next month",
"current_pay": "50k",
"desired_pay": "120k",
"is_willing_to_relocate": true,
"key_skills": "Programming, management, fishing",
"notes": "Molestiae dolor quaerat quasi aperiam deleniti officiis repellat.",
"source": "Google",
"is_hot": false,
"is_active": true,
"is_registered": false,
"contact_id": 4655,
"owner_id": 1779,
"entered_by_id": 5229,
"date_created": "2022-06-11T12:54:25.506Z",
"date_modified": "2022-06-15T15:58:34.291Z",
"_links": {...},
"_embedded": {...}
}
}
}
Creating candidate list items attaches the specified candidates to a list.
required
string
The ID of the candidate list.
array
curl -X POST \
https://api.catsone.com/v3/candidates/lists/6320/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"candidate_id":1232}]}'
Deleting a candidate list item removes a candidate from a list.
required
string
The ID of the candidate list.
required
string
The ID of the list item to delete.
curl -X DELETE \
https://api.catsone.com/v3/candidates/lists/1092/items/102 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the candidate to return applications for.
required
string
The current page number of list items to return.
required
string
The number of list items to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/667/applications \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 614,
"_links": {...},
"_embedded": {
"applications": [
{
"id": 3846,
"job_id": "5744",
"date_created": "2022-04-01T01:07:00.703Z",
"_links": {...},
"_embedded": {
"fields": []
}
},
{...}
]
}
}
required
string
The ID of the applications to return.
required
string
The current page number of list items to return.
required
string
The number of list items to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/applications/5770 \
-H 'authorization: Token <Your API Key>'
{
"id": 3846,
"job_id": "5744",
"date_created": "2022-04-01T01:07:00.703Z",
"_links": {...},
"_embedded": {
"fields": []
}
}
required
string
The ID of the candidate to return tags for.
required
string
The current page number of tags to return.
required
string
The number of tags to return per page.
curl -X GET \
https://api.catsone.com/v3/candidates/1970/tags \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 629,
"_links": {...},
"_embedded": {
"tags": [
{
"id": 4794,
"parent_id": 2791,
"title": "My Cool Tag Name",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This will replace all tags on the candidate with the tags specified in this call. To remove all tags from an item, send an empty tag array.
required
string
The ID of the candidate to replace tags on.
array
curl -X POST \
https://api.catsone.com/v3/candidates/8551/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
This will not delete any existing tags on the candidate.
required
string
The ID of the candidate to attach tags to.
array
curl -X PUT \
https://api.catsone.com/v3/candidates/3075/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
Detaches an individual tag from the candidate.
required
string
The ID of the candidate to detach the tag from.
required
string
The ID of the tag to detach.
curl -X DELETE \
https://api.catsone.com/v3/candidates/8222/tags/3644 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the candidate to get the thumbnail of.
curl -X GET \
https://api.catsone.com/v3/candidates/5339/thumbnail \
-H 'authorization: Token <Your API Key>'
{
"source": "attachment",
"attachment_id": 5111,
"url": "https://perry.info",
"_links": {...}
}
required
string
The ID of the candidate to change the thumbnail of.
required
string
One of attachment
, gravatar
, or disabled
.
number
Only required if source is set to attachment
(must be an attachment belonging to the data item)
curl -X PUT \
https://api.catsone.com/v3/candidates/9722/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":6898}'
required
string
The current page number of companies to return.
required
string
The number of companies to return per page.
curl -X GET \
https://api.catsone.com/v3/companies \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 518,
"_links": {...},
"_embedded": {
"companies": [
{
"id": 3404,
"owner_id": 1974,
"name": "Schmidt, Schmitt and Bartoletti",
"website": "https://alanna.com",
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"entered_by_id": 2984,
"social_media_urls": [],
"notes": "Qui dolor id reiciendis corporis est consequatur harum nihil et.",
"is_hot": false,
"key_technologies": "",
"billing_contact_id": 4942,
"user_groups": [],
"status_id": 1327,
"date_created": "2022-10-03T17:51:25.572Z",
"date_modified": "2022-03-26T02:03:43.197Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the company to return.
curl -X GET \
https://api.catsone.com/v3/companies/3404 \
-H 'authorization: Token <Your API Key>'
{
"id": 3404,
"owner_id": 1974,
"name": "Schmidt, Schmitt and Bartoletti",
"website": "https://alanna.com",
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"entered_by_id": 2984,
"social_media_urls": [],
"notes": "Qui dolor id reiciendis corporis est consequatur harum nihil et.",
"is_hot": false,
"key_technologies": "",
"billing_contact_id": 4942,
"user_groups": [],
"status_id": 1327,
"date_created": "2022-10-03T17:51:25.572Z",
"date_modified": "2022-03-26T02:03:43.197Z",
"_links": {...},
"_embedded": {...}
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
required
string
When this flag is set to true, if a duplicate record is found to the one being created, an error will be thrown instead of creating a duplicate record. Defaults to false.
required
string
required
number
string
array
An array of phone objects. Each phone object should contain three keys: number
, extension
, and type
, as described here
[
{
"number": <phone number with country code>,
"extension": "<optional extension>",
"type": "<phone number type>",
}
]
object
An object containing the address for the company with the following structure:
{
"street": "<street>",
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
number
array
string
boolean
string
number
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this company.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
array
User groups allowed to access this company
curl -X POST \
https://api.catsone.com/v3/companies \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Durgan - Trantow","owner_id":3418,"website":"https://felton.net","phones":[{"number":"+16124063451","extension":"664","type":"Main"}],"address":{"street":"732 Zita Estates","city":"Nitzscheport","state":"Kansas","postal_code":"94543-5467"},"country_code":"US","entered_by_id":1093,"social_media_urls":[],"notes":"Et sit qui aliquid numquam alias vel inventore.","is_hot":true,"key_technologies":"","billing_contact_id":3946,"custom_fields":[{"id":8474,"value":"lorem"}],"user_groups":[]}'
required
string
The ID of the company to update.
required
string
required
number
string
array
An array of phone objects. Each phone object should contain three keys: number
, extension
, and type
, as described here
[
{
"number": <phone number with country code>,
"extension": "<optional extension>",
"type": "<phone number type>",
}
]
object
An object containing the address for the company with the following structure:
{
"street": "<street>",
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
number
array
string
boolean
string
number
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this company.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
array
User groups allowed to access this company
curl -X PUT \
https://api.catsone.com/v3/companies/2314 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Durgan - Trantow","owner_id":3418,"website":"https://felton.net","phones":[{"number":"+16124063451","extension":"664","type":"Main"}],"address":{"street":"732 Zita Estates","city":"Nitzscheport","state":"Kansas","postal_code":"94543-5467"},"country_code":"US","entered_by_id":1093,"social_media_urls":[],"notes":"Et sit qui aliquid numquam alias vel inventore.","is_hot":true,"key_technologies":"","billing_contact_id":3946,"custom_fields":[{"id":8474,"value":"lorem"}],"user_groups":[]}'
required
string
The ID of the company to delete.
curl -X DELETE \
https://api.catsone.com/v3/companies/3477 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the company to fetch tasks concerning.
required
string
The current page number of tasks to return.
required
string
The number of task items to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/902/tasks \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 544,
"_links": {...},
"_embedded": {
"tasks": [
{
"id": 3609,
"data_item": {
"id": 6840,
"type": "company"
},
"entered_by_id": 2281,
"assigned_to_id": 7319,
"description": "Dignissimos in sit porro rerum quia.",
"priority": 2,
"date_due": "2022-12-19T20:00:55.351Z",
"is_completed": true,
"date_completed": "2022-01-02T19:44:55.274Z",
"date_created": "2022-08-12T05:38:50.987Z",
"date_updated": "2022-02-18T17:16:28.780Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The string to search within companies for.
required
string
The current page number of companies to return.
required
string
The number of companies to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/search \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 518,
"_links": {...},
"_embedded": {
"companies": [
{
"id": 3404,
"owner_id": 1974,
"name": "Schmidt, Schmitt and Bartoletti",
"website": "https://alanna.com",
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"entered_by_id": 2984,
"social_media_urls": [],
"notes": "Qui dolor id reiciendis corporis est consequatur harum nihil et.",
"is_hot": false,
"key_technologies": "",
"billing_contact_id": 4942,
"user_groups": [],
"status_id": 1327,
"date_created": "2022-10-03T17:51:25.572Z",
"date_modified": "2022-03-26T02:03:43.197Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This section describes the filters and fields that can be used to filter search results for this endpoint. The example given is the most simple way to pass a filter into the call. For a more in-depth explanation of boolean filtering, consult the section near the top of this page dealing with filtering.
The following are all the Company fields that can currently be filtered on, and which filters can be used on each:
`id` - greater_than, less_than, between, exactly, is_empty
`owner_id` - greater_than, less_than, between, exactly, is_empty
`name` - contains, exactly, is_empty
`website` - contains, exactly, is_empty
`address.street` - contains, exactly, is_empty
`address.city` - contains, exactly, is_empty
`address.state` - contains, exactly, is_empty
`address.postal_code` - geo_distance, contains, exactly, is_empty
`country_code` - contains, exactly, is_empty
`phones.primary` - contains, exactly, is_empty
`phones.secondary` - contains, exactly, is_empty
`phones.fax` - contains, exactly, is_empty
`entered_by_id` - greater_than, less_than, between, exactly, is_empty
`notes` - contains, exactly, is_empty
`is_hot` - exactly, is_empty
`key_technologies` - contains, exactly, is_empty
`billing_contact_id` - greater_than, less_than, between, exactly, is_empty
`status_id` - greater_than, less_than, between, exactly, is_empty
`date_created` - greater_than, less_than, between, is_empty
`date_modified` - greater_than, less_than, between, is_empty
required
string
The optional string to search within companies for.
required
string
The current page number of companies to return.
required
string
The number of companies to return per page.
required
string
The field to filter on. See the above list to determine which fields can be filtered.
required
string
The filter to use. See the above list to determine which fields allow what filters.
required
string
The value to filter by. Different filters take different value types (string, array, int). See the section in the introduction to see what values each filter accepts.
curl -X POST \
https://api.catsone.com/v3/companies/search \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
{
"count": 25,
"total": 518,
"_links": {...},
"_embedded": {
"companies": [
{
"id": 3404,
"owner_id": 1974,
"name": "Schmidt, Schmitt and Bartoletti",
"website": "https://alanna.com",
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"entered_by_id": 2984,
"social_media_urls": [],
"notes": "Qui dolor id reiciendis corporis est consequatur harum nihil et.",
"is_hot": false,
"key_technologies": "",
"billing_contact_id": 4942,
"user_groups": [],
"status_id": 1327,
"date_created": "2022-10-03T17:51:25.572Z",
"date_modified": "2022-03-26T02:03:43.197Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The company to return phones for.
required
string
The current page number of phones to return.
required
string
The number of phones to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/325/phones \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 822,
"_links": {...},
"_embedded": {
"phones": [
{
"id": 3408,
"number": "623.714.4685 x4297",
"extension": "612",
"type": "Mobile",
"date_created": "2022-07-05T02:56:11.498Z",
"date_modified": "2022-07-21T16:20:35.365Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The company to return the phone for.
required
string
The ID of the phone to return.
curl -X GET \
https://api.catsone.com/v3/companies/3712/phones/2169 \
-H 'authorization: Token <Your API Key>'
{
"id": 3408,
"number": "623.714.4685 x4297",
"extension": "612",
"type": "Mobile",
"date_created": "2022-07-05T02:56:11.498Z",
"date_modified": "2022-07-21T16:20:35.365Z",
"_links": {...},
"_embedded": {...}
}
required
string
The company to create the phone for.
required
string
This number MUST begin with the country code. It will not be parsed correctly otherwise.
string
required
string
One of fax
, main
, or other
.
curl -X POST \
https://api.catsone.com/v3/companies/2913/phones \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"664","type":"Main"}'
required
string
The company to update the phone for.
required
string
The ID of the phone to update.
required
string
This number MUST begin with the country code. It will not be parsed correctly otherwise.
string
required
string
One of fax
, main
, or other
.
curl -X PUT \
https://api.catsone.com/v3/companies/7728/phones/5181 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"664","type":"Main"}'
required
string
The company to delete the phone from.
required
string
The ID of the phone to delete.
curl -X DELETE \
https://api.catsone.com/v3/companies/3743/phones/123 \
-H 'authorization: Token <Your API Key>'
List all custom field definitions associated with the company data item type. Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
or number
.
required
string
The current page number of custom field definitions to return.
required
string
The number of custom field definitions to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 776,
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 832,
"data_item_type": "company",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
},
{...}
]
}
}
Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
or number
.
required
string
The ID of the custom field definition to return.
curl -X GET \
https://api.catsone.com/v3/companies/custom_fields/832 \
-H 'authorization: Token <Your API Key>'
{
"id": 832,
"data_item_type": "company",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
}
List all custom field values associated with a company. This returns the values of all custom fields for the company
data item type for a single company.
required
string
The ID of the company to return custom fields for.
required
string
The current page number of custom fields to return.
required
string
The number of custom fields to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/9613/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": "764",
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Get a single custom field value for a company.
required
string
The ID of the company that the custom field belongs to.
required
string
The ID of the custom field to return.
curl -X GET \
https://api.catsone.com/v3/companies/8408/custom_fields/7433 \
-H 'authorization: Token <Your API Key>'
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the company that the custom field belongs to.
required
string
The ID of the custom field to update.
required
string
curl -X PUT \
https://api.catsone.com/v3/companies/649/custom_fields/3692 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"fredy"}'
required
string
The current page number of statuses to return.
required
string
The number of statuses to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/statuses \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 738,
"_links": {...},
"_embedded": {
"statuses": [
{
"id": 8486,
"title": "Lead",
"mapping": "lead",
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
},
{...}
]
}
}
required
string
The ID of the status to return.
curl -X GET \
https://api.catsone.com/v3/companies/statuses/8486 \
-H 'authorization: Token <Your API Key>'
{
"id": 8486,
"title": "Lead",
"mapping": "lead",
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
}
required
string
The ID of the company that the status is being attached to.
required
number
The ID of the status to attach.
array
An array of objects each containing the ID of an attached trigger and a boolean representing whether or not to fire the trigger.
If the triggers
parameter is not set, all required triggers will be fired as well as all triggers that are marked as optional and on by default. Optional triggers that are off by default will not fire.
If the triggers
parameter is specified, all triggers that are attached to the status must be included in the array and the API will make no assumptions about which triggers to fire.
Example:
[
{
"id": <trigger ID>,
"fire": <boolean>
}
]
curl -X POST \
https://api.catsone.com/v3/companies/8656/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":466,"triggers":[{"id":5728,"fire":false}]}'
required
string
The ID of the company to return attachments for.
required
string
The current page number of attachments to return.
required
string
The number of attachments to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/4109/attachments \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 325,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 9981,
"filename": "readme.txt",
"is_resume": false,
"size": "",
"version": "",
"data_item": {
"id": 7554,
"type": "candidate"
}
},
{...}
]
}
}
required
string
The ID of the company that the attachment is being attached to.
required
string
The name to save the file being uploaded as.
curl -X POST \
https://api.catsone.com/v3/companies/3757/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
required
string
The current page number of lists to return.
required
string
The number of lists to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/lists \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 375,
"_links": {...},
"_embedded": {
"lists": [
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the company list to return.
curl -X GET \
https://api.catsone.com/v3/companies/lists/2560 \
-H 'authorization: Token <Your API Key>'
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
}
required
string
string
curl -X POST \
https://api.catsone.com/v3/companies/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"sint","notes":"Enim a explicabo dolor."}'
required
string
The ID of the company list to delete.
curl -X DELETE \
https://api.catsone.com/v3/companies/lists/2154 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the company list to return items for.
required
string
The current page number of list items to return.
required
string
The number of list items to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/lists/1828/items \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 242,
"_links": {...},
"_embedded": {
"items": [
{
"id": 363,
"date_created": "2022-12-14T18:33:56.629Z",
"company_id": 323,
"_links": {...},
"_embedded": {
"company": {
"id": 3404,
"owner_id": 1974,
"name": "Schmidt, Schmitt and Bartoletti",
"website": "https://alanna.com",
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"entered_by_id": 2984,
"social_media_urls": [],
"notes": "Qui dolor id reiciendis corporis est consequatur harum nihil et.",
"is_hot": false,
"key_technologies": "",
"billing_contact_id": 4942,
"user_groups": [],
"status_id": 1327,
"date_created": "2022-10-03T17:51:25.572Z",
"date_modified": "2022-03-26T02:03:43.197Z",
"_links": {...},
"_embedded": {...}
}
}
},
{...}
]
}
}
required
string
The ID of the company list the item belongs to.
required
string
The ID of the company list item to return.
curl -X GET \
https://api.catsone.com/v3/companies/lists/8360/items/2744 \
-H 'authorization: Token <Your API Key>'
{
"id": 363,
"date_created": "2022-12-14T18:33:56.629Z",
"company_id": 323,
"_links": {...},
"_embedded": {
"company": {
"id": 3404,
"owner_id": 1974,
"name": "Schmidt, Schmitt and Bartoletti",
"website": "https://alanna.com",
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"entered_by_id": 2984,
"social_media_urls": [],
"notes": "Qui dolor id reiciendis corporis est consequatur harum nihil et.",
"is_hot": false,
"key_technologies": "",
"billing_contact_id": 4942,
"user_groups": [],
"status_id": 1327,
"date_created": "2022-10-03T17:51:25.572Z",
"date_modified": "2022-03-26T02:03:43.197Z",
"_links": {...},
"_embedded": {...}
}
}
}
Creating company list items attaches the specified companies to a list.
required
string
The ID of the company list.
array
curl -X POST \
https://api.catsone.com/v3/companies/lists/2599/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"company_id":3974}]}'
Deleting a company list item removes a company from a list.
required
string
The ID of the company list.
required
string
The ID of the list item to delete.
curl -X DELETE \
https://api.catsone.com/v3/companies/lists/5569/items/6672 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the company to return tags for.
required
string
The current page number of tags to return.
required
string
The number of tags to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/536/tags \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 629,
"_links": {...},
"_embedded": {
"tags": [
{
"id": 4794,
"parent_id": 2791,
"title": "My Cool Tag Name",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This will replace all tags on the company with the tags specified in this call. To remove all tags from an item, send an empty tag array.
required
string
The ID of the company to replace tags on.
array
curl -X POST \
https://api.catsone.com/v3/companies/360/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
This will not delete any existing tags on the company.
required
string
The ID of the company to attach tags to.
array
curl -X PUT \
https://api.catsone.com/v3/companies/457/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
Detaches an individual tag from the company.
required
string
The ID of the company to detach the tag from.
required
string
The ID of the tag to detach.
curl -X DELETE \
https://api.catsone.com/v3/companies/7097/tags/1317 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the company to return departments for.
required
string
The current page number of departments to return.
required
string
The number of departments to return per page.
curl -X GET \
https://api.catsone.com/v3/companies/881/departments \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 295,
"_links": {...},
"_embedded": {
"departments": [
{
"id": 994,
"name": "Mayer and Sons",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the department to return.
curl -X GET \
https://api.catsone.com/v3/companies/departments/994 \
-H 'authorization: Token <Your API Key>'
{
"id": 994,
"name": "Mayer and Sons",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the company to add department on.
required
string
curl -X POST \
https://api.catsone.com/v3/companies/705/departments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Rippin - Streich"}'
required
string
The ID of the department to update.
required
string
curl -X PUT \
https://api.catsone.com/v3/companies/departments/1422 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Rippin - Streich"}'
required
string
The ID of the department to delete.
curl -X DELETE \
https://api.catsone.com/v3/companies/departments/2594 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the company to get the thumbnail of.
curl -X GET \
https://api.catsone.com/v3/companies/8998/thumbnail \
-H 'authorization: Token <Your API Key>'
{
"source": "attachment",
"attachment_id": 5111,
"url": "https://perry.info",
"_links": {...}
}
required
string
The ID of the company to change the thumbnail of.
required
string
One of attachment
, clearbit
, or disabled
.
number
Only required if source is set to attachment
(must be an attachment belonging to the data item)## Trigger (object)
number
string
boolean
boolean
object
curl -X PUT \
https://api.catsone.com/v3/companies/5825/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":8976,"id":6391,"description":"Send Candidate Status Change Notification","is_required":true,"is_default":false,"_links":{}}'
required
string
The current page number of contacts to return.
required
string
The number of contacts to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 313,
"_links": {...},
"_embedded": {
"contacts": [
{
"id": 6016,
"first_name": "Alexa",
"last_name": "Quigley",
"title": "District Research Officer",
"reports_to_id": 882,
"emails": {
"primary": "Adela_Lindgren@hotmail.com",
"secondary": "Hector_Runte@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"is_hot": false,
"notes": "Quia nobis numquam aut quibusdam eum sunt eum non ut.",
"entered_by_id": 5702,
"status_id": 3683,
"date_created": "2022-02-19T22:51:52.904Z",
"date_modified": "2022-01-01T22:14:24.303Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the contact to return.
curl -X GET \
https://api.catsone.com/v3/contacts/6016 \
-H 'authorization: Token <Your API Key>'
{
"id": 6016,
"first_name": "Alexa",
"last_name": "Quigley",
"title": "District Research Officer",
"reports_to_id": 882,
"emails": {
"primary": "Adela_Lindgren@hotmail.com",
"secondary": "Hector_Runte@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"is_hot": false,
"notes": "Quia nobis numquam aut quibusdam eum sunt eum non ut.",
"entered_by_id": 5702,
"status_id": 3683,
"date_created": "2022-02-19T22:51:52.904Z",
"date_modified": "2022-01-01T22:14:24.303Z",
"_links": {...},
"_embedded": {...}
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
required
string
When this flag is set to true, if a duplicate record is found to the one being created, an error will be thrown instead of creating a duplicate record. Defaults to false.
required
string
required
string
required
number
The ID of the user that owns this contact record.
required
number
The ID of the company this contact belongs to.
string
The contact's job title.
number
The ID of the contact that this contact reports to.
boolean
array
An array of email objects. Each email object should contain two keys: email
and is_primary
, as described here
[
{
"email": <email>,
"is_primary": "<is this the primary email?>"
}
]
array
An array of phone objects. Each phone object should contain three keys: number
, extension
, and type
, as described here
[
{
"number": <phone number with country code>,
"extension": "<optional extension>",
"type": "<phone number type>",
}
]
object
An object containing the address for the contact with the following structure:
{
"street": "<street>",
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
array
boolean
string
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this contact.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
curl -X POST \
https://api.catsone.com/v3/contacts \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Eve","last_name":"Predovic","owner_id":1800,"company_id":8847,"title":"Global Communications Analyst","reports_to_id":7103,"has_left_company":true,"emails":[{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}],"phones":[{"number":"+16124063451","extension":"8371","type":"Mobile"}],"address":{"street":"98742 Robb Isle","city":"Devinland","state":"Rhode Island","postal_code":"75389-5570"},"country_code":"US","social_media_urls":[],"is_hot":true,"notes":"Voluptate illo aut.","custom_fields":[{"id":8474,"value":"lorem"}]}'
required
string
The ID of the contact to update.
required
string
required
string
required
number
The ID of the user that owns this contact record.
required
number
The ID of the company this contact belongs to.
string
The contact's job title.
number
The ID of the contact that this contact reports to.
boolean
array
An array of email objects. Each email object should contain two keys: email
and is_primary
, as described here
[
{
"email": <email>,
"is_primary": "<is this the primary email?>"
}
]
array
An array of phone objects. Each phone object should contain three keys: number
, extension
, and type
, as described here
[
{
"number": <phone number with country code>,
"extension": "<optional extension>",
"type": "<phone number type>",
}
]
object
An object containing the address for the contact with the following structure:
{
"street": "<street>",
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
array
boolean
string
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this contact.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
curl -X PUT \
https://api.catsone.com/v3/contacts/6663 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Eve","last_name":"Predovic","owner_id":1800,"company_id":8847,"title":"Global Communications Analyst","reports_to_id":7103,"has_left_company":true,"emails":[{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}],"phones":[{"number":"+16124063451","extension":"8371","type":"Mobile"}],"address":{"street":"98742 Robb Isle","city":"Devinland","state":"Rhode Island","postal_code":"75389-5570"},"country_code":"US","social_media_urls":[],"is_hot":true,"notes":"Voluptate illo aut.","custom_fields":[{"id":8474,"value":"lorem"}]}'
required
string
The ID of the contact to delete.
curl -X DELETE \
https://api.catsone.com/v3/contacts/2107 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the contact to fetch tasks concerning.
required
string
The current page number of tasks to return.
required
string
The number of task items to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/605/tasks \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 885,
"_links": {...},
"_embedded": {
"tasks": [
{
"id": 3609,
"data_item": {
"id": 7030,
"type": "contact"
},
"entered_by_id": 6824,
"assigned_to_id": 8425,
"description": "Rerum commodi perferendis excepturi deserunt laboriosam earum.",
"priority": 2,
"date_due": "2022-06-19T14:20:58.345Z",
"is_completed": true,
"date_completed": "2022-11-02T17:27:01.941Z",
"date_created": "2022-03-26T05:51:56.311Z",
"date_updated": "2022-03-16T20:34:33.876Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The string to search within contacts for.
required
string
The current page number of contacts to return.
required
string
The number of contacts to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/search \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 313,
"_links": {...},
"_embedded": {
"contacts": [
{
"id": 6016,
"first_name": "Alexa",
"last_name": "Quigley",
"title": "District Research Officer",
"reports_to_id": 882,
"emails": {
"primary": "Adela_Lindgren@hotmail.com",
"secondary": "Hector_Runte@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"is_hot": false,
"notes": "Quia nobis numquam aut quibusdam eum sunt eum non ut.",
"entered_by_id": 5702,
"status_id": 3683,
"date_created": "2022-02-19T22:51:52.904Z",
"date_modified": "2022-01-01T22:14:24.303Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This section describes the filters and fields that can be used to filter search results for this endpoint. The example given is the most simple way to pass a filter into the call. For a more in-depth explanation of boolean filtering, consult the section near the top of this page dealing with filtering.
The following are all the Contact fields that can currently be filtered on, and which filters can be used on each:
`id` - greater_than, less_than, between, exactly, is_empty
`first_name` - contains, exactly, is_empty
`last_name` - contains, exactly, is_empty
`title` - contains, exactly, is_empty
`reports_to_id` - greater_than, less_than, between, exactly, is_empty
`emails.primary` - contains, exactly, is_empty
`emails.secondary` - contains, exactly, is_empty
`address.street` - contains, exactly, is_empty
`address.city` - contains, exactly, is_empty
`address.state` - contains, exactly, is_empty
`address.postal_code` - geo_distance, contains, exactly, is_empty
`country_code` - contains, exactly, is_empty
`phones.other` - contains, exactly, is_empty
`phones.cell` - contains, exactly, is_empty
`phones.work` - contains, exactly, is_empty
`notes` - contains, exactly, is_empty
`is_hot` - exactly, is_empty
`status_id` - greater_than, less_than, between, exactly, is_empty
`entered_by_id` - greater_than, less_than, between, exactly, is_empty
`date_created` - greater_than, less_than, between, is_empty
`date_modified` - greater_than, less_than, between, is_empty
required
string
The optional string to search within contacts for.
required
string
The current page number of contacts to return.
required
string
The number of contacts to return per page.
required
string
The field to filter on. See the above list to determine which fields can be filtered.
required
string
The filter to use. See the above list to determine which fields allow what filters.
required
string
The value to filter by. Different filters take different value types (string, array, int). See the section in the introduction to see what values each filter accepts.
curl -X POST \
https://api.catsone.com/v3/contacts/search \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
{
"count": 25,
"total": 313,
"_links": {...},
"_embedded": {
"contacts": [
{
"id": 6016,
"first_name": "Alexa",
"last_name": "Quigley",
"title": "District Research Officer",
"reports_to_id": 882,
"emails": {
"primary": "Adela_Lindgren@hotmail.com",
"secondary": "Hector_Runte@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"is_hot": false,
"notes": "Quia nobis numquam aut quibusdam eum sunt eum non ut.",
"entered_by_id": 5702,
"status_id": 3683,
"date_created": "2022-02-19T22:51:52.904Z",
"date_modified": "2022-01-01T22:14:24.303Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The contact to return phones for.
required
string
The current page number of phones to return.
required
string
The number of phones to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/570/phones \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 822,
"_links": {...},
"_embedded": {
"phones": [
{
"id": 3408,
"number": "623.714.4685 x4297",
"extension": "612",
"type": "Mobile",
"date_created": "2022-07-05T02:56:11.498Z",
"date_modified": "2022-07-21T16:20:35.365Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The contact to return the phone for.
required
string
The ID of the phone to return.
curl -X GET \
https://api.catsone.com/v3/contacts/9214/phones/2169 \
-H 'authorization: Token <Your API Key>'
{
"id": 3408,
"number": "623.714.4685 x4297",
"extension": "612",
"type": "Mobile",
"date_created": "2022-07-05T02:56:11.498Z",
"date_modified": "2022-07-21T16:20:35.365Z",
"_links": {...},
"_embedded": {...}
}
required
string
The contact to create the phone for.
required
string
This number MUST begin with the country code. It will not be parsed correctly otherwise.
string
required
string
One of mobile
, home
, work
, fax
, main
, or other
.
curl -X POST \
https://api.catsone.com/v3/contacts/8406/phones \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
required
string
The contact to update the phone for.
required
string
The ID of the phone to update.
required
string
This number MUST begin with the country code. It will not be parsed correctly otherwise.
string
required
string
One of mobile
, home
, work
, fax
, main
, or other
.
curl -X PUT \
https://api.catsone.com/v3/contacts/8436/phones/3113 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
required
string
The contact to delete the phone from.
required
string
The ID of the phone to delete.
curl -X DELETE \
https://api.catsone.com/v3/contacts/7803/phones/5891 \
-H 'authorization: Token <Your API Key>'
required
string
The contact to return emails for.
required
string
The current page number of emails to return.
required
string
The number of emails to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/4826/emails \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 957,
"_links": {...},
"_embedded": {
"emails": [
{
"id": 6754,
"email": "Virginie7@hotmail.com",
"is_primary": true,
"date_created": "2022-06-24T23:25:26.606Z",
"date_modified": "2022-02-27T05:37:10.167Z",
"_links": {...}
},
{...}
]
}
}
required
string
The contact to return the email for.
required
string
The ID of the email to return.
curl -X GET \
https://api.catsone.com/v3/contacts/8890/emails/3514 \
-H 'authorization: Token <Your API Key>'
{
"id": 6754,
"email": "Virginie7@hotmail.com",
"is_primary": true,
"date_created": "2022-06-24T23:25:26.606Z",
"date_modified": "2022-02-27T05:37:10.167Z",
"_links": {...}
}
required
string
The contact to create the email for.
required
string
boolean
If a record has any number of emails, exactly one of them must be marked as primary.
curl -X POST \
https://api.catsone.com/v3/contacts/8171/emails \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}'
required
string
The contact to update the email for.
required
string
The ID of the email to update.
required
string
boolean
If a record has any number of emails, exactly one of them must be marked as primary.
curl -X PUT \
https://api.catsone.com/v3/contacts/6615/emails/860 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Korbin_Bergstrom33@gmail.com","is_primary":true}'
required
string
The contact to delete the email from.
required
string
The ID of the email to delete.
curl -X DELETE \
https://api.catsone.com/v3/contacts/3394/emails/5325 \
-H 'authorization: Token <Your API Key>'
List all custom field definitions associated with the contact data item type. Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
or number
.
required
string
The current page number of custom field definitions to return.
required
string
The number of custom field definitions to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 944,
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 832,
"data_item_type": "contact",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
},
{...}
]
}
}
Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
or number
.
required
string
The ID of the custom field definition to return.
curl -X GET \
https://api.catsone.com/v3/contacts/custom_fields/832 \
-H 'authorization: Token <Your API Key>'
{
"id": 832,
"data_item_type": "contact",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
}
List all custom field values associated with a contact. This returns the values of all custom fields for the contact
data item type for a single contact.
required
string
The ID of the contact to return custom fields for.
required
string
The current page number of custom fields to return.
required
string
The number of custom fields to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/8360/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": "764",
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Get a single custom field value for a contact.
required
string
The ID of the contact that the custom field belongs to.
required
string
The ID of the custom field to return.
curl -X GET \
https://api.catsone.com/v3/contacts/1018/custom_fields/5985 \
-H 'authorization: Token <Your API Key>'
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the contact that the custom field belongs to.
required
string
The ID of the custom field to update.
required
string
curl -X PUT \
https://api.catsone.com/v3/contacts/8219/custom_fields/5922 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"fredy"}'
List all activities associated with a contact.
required
string
The ID of the contact to return activities for.
required
string
The current page number of activities to return.
required
string
The number of activities to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/3825/activities \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 321,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 124,
"data_item": {
"id": 7030,
"type": "contact"
},
"date_created": "2022-09-04T20:40:16.101Z",
"regarding_id": 3931,
"type": "type_other",
"notes": "Added candidate to pipeline.",
"annotation": "General",
"entered_by_id": 2023,
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Log an activity against a contact.
required
string
The ID of the contact to create an activity for.
required
string
One of the following activity types: email
, meeting
, call_talked
, call_lvm
, call_missed
, text_message
or other
.
number
The ID of the job order that this activity is regarding. Leave null
for a general activity.
string
string
The datetime the activity took place. If not specified it defaults to the current date and time.
curl -X POST \
https://api.catsone.com/v3/contacts/7057/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":9940,"notes":"Provident et repudiandae reiciendis quidem dolores exercitationem saepe aut.","date":"2022-04-14T05:25:50.723Z"}'
required
string
The current page number of statuses to return.
required
string
The number of statuses to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/statuses \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 768,
"_links": {...},
"_embedded": {
"statuses": [
{
"id": 8486,
"title": "Employee",
"mapping": "human_resources",
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
},
{...}
]
}
}
required
string
The ID of the status to return.
curl -X GET \
https://api.catsone.com/v3/contacts/statuses/8486 \
-H 'authorization: Token <Your API Key>'
{
"id": 8486,
"title": "Employee",
"mapping": "human_resources",
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
}
required
string
The ID of the contact that the status is being attached to.
required
string
Whether a corresponding activity should be created automatically. This mimics what happens when a pipeline is created from the CATS UI. Defaults to false.
required
number
The ID of the status to attach.
array
An array of objects each containing the ID of an attached trigger and a boolean representing whether or not to fire the trigger.
If the triggers
parameter is not set, all required triggers will be fired as well as all triggers that are marked as optional and on by default. Optional triggers that are off by default will not fire.
If the triggers
parameter is specified, all triggers that are attached to the status must be included in the array and the API will make no assumptions about which triggers to fire.
Example:
[
{
"id": <trigger ID>,
"fire": <boolean>
}
]
curl -X POST \
https://api.catsone.com/v3/contacts/4248/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":466,"triggers":[{"id":5728,"fire":false}]}'
required
string
The ID of the contact to return attachments for.
required
string
The current page number of attachments to return.
required
string
The number of attachments to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/2082/attachments \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 325,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 9981,
"filename": "readme.txt",
"is_resume": false,
"size": "",
"version": "",
"data_item": {
"id": 7554,
"type": "candidate"
}
},
{...}
]
}
}
required
string
The ID of the contact that the attachment is being attached to.
required
string
The name to save the file being uploaded as.
curl -X POST \
https://api.catsone.com/v3/contacts/471/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
required
string
The current page number of lists to return.
required
string
The number of lists to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/lists \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 375,
"_links": {...},
"_embedded": {
"lists": [
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the contact list to return.
curl -X GET \
https://api.catsone.com/v3/contacts/lists/3117 \
-H 'authorization: Token <Your API Key>'
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
}
required
string
string
curl -X POST \
https://api.catsone.com/v3/contacts/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"sint","notes":"Enim a explicabo dolor."}'
required
string
The ID of the contact list to delete.
curl -X DELETE \
https://api.catsone.com/v3/contacts/lists/7242 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the contact list to return items for.
required
string
The current page number of list items to return.
required
string
The number of list items to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/lists/3657/items \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 455,
"_links": {...},
"_embedded": {
"items": [
{
"id": 415,
"date_created": "2022-02-26T20:30:51.814Z",
"contact_id": 8828,
"_links": {...},
"_embedded": {
"contact": {
"id": 6016,
"first_name": "Alexa",
"last_name": "Quigley",
"title": "District Research Officer",
"reports_to_id": 882,
"emails": {
"primary": "Adela_Lindgren@hotmail.com",
"secondary": "Hector_Runte@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"is_hot": false,
"notes": "Quia nobis numquam aut quibusdam eum sunt eum non ut.",
"entered_by_id": 5702,
"status_id": 3683,
"date_created": "2022-02-19T22:51:52.904Z",
"date_modified": "2022-01-01T22:14:24.303Z",
"_links": {...},
"_embedded": {...}
}
}
},
{...}
]
}
}
required
string
The ID of the contact list the item belongs to.
required
string
The ID of the contact list item to return.
curl -X GET \
https://api.catsone.com/v3/contacts/lists/198/items/1137 \
-H 'authorization: Token <Your API Key>'
{
"id": 415,
"date_created": "2022-02-26T20:30:51.814Z",
"contact_id": 8828,
"_links": {...},
"_embedded": {
"contact": {
"id": 6016,
"first_name": "Alexa",
"last_name": "Quigley",
"title": "District Research Officer",
"reports_to_id": 882,
"emails": {
"primary": "Adela_Lindgren@hotmail.com",
"secondary": "Hector_Runte@yahoo.com"
},
"address": {
"street": "24626 Padberg Junction",
"city": "New Idell",
"state": "ME",
"postal_code": "62687-6982"
},
"country_code": "US",
"social_media_urls": [],
"is_hot": false,
"notes": "Quia nobis numquam aut quibusdam eum sunt eum non ut.",
"entered_by_id": 5702,
"status_id": 3683,
"date_created": "2022-02-19T22:51:52.904Z",
"date_modified": "2022-01-01T22:14:24.303Z",
"_links": {...},
"_embedded": {...}
}
}
}
Creating contact list items attaches the specified contacts to a list.
required
string
The ID of the contact list.
array
curl -X POST \
https://api.catsone.com/v3/contacts/lists/6592/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"contact_id":3180}]}'
Deleting a contact list item removes a contact from a list.
required
string
The ID of the contact list.
required
string
The ID of the list item to delete.
curl -X DELETE \
https://api.catsone.com/v3/contacts/lists/5889/items/4297 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the contact to return tags for.
required
string
The current page number of tags to return.
required
string
The number of tags to return per page.
curl -X GET \
https://api.catsone.com/v3/contacts/1289/tags \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 629,
"_links": {...},
"_embedded": {
"tags": [
{
"id": 4794,
"parent_id": 2791,
"title": "My Cool Tag Name",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This will replace all tags on the contact with the tags specified in this call. To remove all tags from an item, send an empty tag array.
required
string
The ID of the contact to replace tags on.
array
curl -X POST \
https://api.catsone.com/v3/contacts/147/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
This will not delete any existing tags on the contact.
required
string
The ID of the contact to attach tags to.
array
curl -X PUT \
https://api.catsone.com/v3/contacts/1600/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
Detaches an individual tag from the contact.
required
string
The ID of the contact to detach the tag from.
required
string
The ID of the tag to detach.
curl -X DELETE \
https://api.catsone.com/v3/contacts/6139/tags/2330 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the contact to get the thumbnail of.
curl -X GET \
https://api.catsone.com/v3/contacts/3011/thumbnail \
-H 'authorization: Token <Your API Key>'
{
"source": "attachment",
"attachment_id": 5111,
"url": "https://perry.info",
"_links": {...}
}
required
string
The ID of the contact to change the thumbnail of.
required
string
One of attachment
, gravatar
, or disabled
.
number
Only required if source is set to attachment
(must be an attachment belonging to the data item)
curl -X PUT \
https://api.catsone.com/v3/contacts/8365/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":6898}'
Events are a record of most of the major actions that have taken place to data items on your account. These are similar to webhooks in their scope, but instead of having to subscribe to webhooks, events are always being recorded and can be polled at your convenience.
This will return up to 25 events starting after (and not including) the provided event id. The resulting hal collection will also contain the next url you need to poll to get the next set of events.
required
string
Get up to 25 events immediately following (but not including) this id
curl -X GET \
https://api.catsone.com/v3/events \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"starting_after_timestamp": 1510864296,
"starting_after_id": 23634,
"last_id": 23659,
"_links": {...},
"_embedded": {
"events": [
{
"id": 23635,
"event_name": "candidate.created",
"data_item": {
"id": 2861,
"type": "candidate"
},
"user_id": 7343,
"timestamp": 1510864358
},
{...}
]
}
}
This will return up to 25 events starting after (and not including) the provided timestamp. The resulting hal collection will also contain the next url you need to poll to get the next set of events. Fetching by id is preferable to fetching by timestamp.
required
string
Get up to 25 events immediately following (but not including) this timestamp
curl -X GET \
https://api.catsone.com/v3/events \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"starting_after_timestamp": 1510864296,
"starting_after_id": 23634,
"last_id": 23659,
"_links": {...},
"_embedded": {
"events": [
{
"id": 23635,
"event_name": "candidate.created",
"data_item": {
"id": 2861,
"type": "candidate"
},
"user_id": 7343,
"timestamp": 1510864358
},
{...}
]
}
}
required
string
The current page number of jobs to return.
required
string
The number of jobs to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 927,
"_links": {...},
"_embedded": {
"jobs": [
{
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the job to return.
curl -X GET \
https://api.catsone.com/v3/jobs/839 \
-H 'authorization: Token <Your API Key>'
{
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
required
string
When this flag is set to true, if a duplicate record is found to the one being created, an error will be thrown instead of creating a duplicate record. Defaults to false.
required
string
required
object
An object containing the location information for the job with the following structure:
{
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
required
number
The ID of the company the job belongs to.
number
The ID of the department the job belongs to (must be a department linked to the specified company)
number
The ID of the user who is the recruiter for the job.
number
The user id of the record owner
string
boolean
string
string
string
string
string
number
string
string
string
number
The ID of the contact associated with the job.
number
The ID of the workflow to assign to pipelines attached to this job. If not specified, will use the default.
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this job.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
array
User groups allowed to access this job
curl -X POST \
https://api.catsone.com/v3/jobs \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Direct Accounts Assistant","location":{"city":"Bodefurt","state":"CA","postal_code":"70841-3728"},"country_code":"US","company_id":9125,"department_id":7615,"recruiter_id":3134,"owner_id":334,"category_name":"","is_hot":false,"start_date":"2022-10-15T03:27:48.584Z","salary":"","max_rate":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":4074,"workflow_id":6686,"custom_fields":[{"id":8474,"value":"lorem"}],"user_groups":[]}'
required
string
The ID of the job to update.
required
string
required
object
An object containing the location information for the job with the following structure:
{
"city": "<city>",
"state": "<state>",
"postal_code": "<postal code>"
}
string
required
number
The ID of the company the job belongs to.
number
The ID of the department the job belongs to (must be a department linked to the specified company)
number
The ID of the user who is the recruiter for the job.
number
The user id of the record owner
string
boolean
string
string
string
string
string
number
string
string
string
number
The ID of the contact associated with the job.
array
An array of custom field objects. Each custom field object should contain two keys: id
and value
. id
is the id of a custom field definition, and value
is the value to be set to that custom field for this job.
[
{
"id": <custom field definition id>,
"value": "<custom field value>"
}
]
array
User groups allowed to access this job
curl -X PUT \
https://api.catsone.com/v3/jobs/2448 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Regional Implementation Officer","location":{"city":"Lake Torrey","state":"WV","postal_code":"26066"},"country_code":"US","company_id":6218,"department_id":6011,"recruiter_id":9242,"owner_id":3502,"category_name":"","is_hot":true,"start_date":"2022-11-30T19:53:50.125Z","salary":"","max_rate":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":9494,"custom_fields":[{"id":8474,"value":"lorem"}],"user_groups":[]}'
required
string
The ID of the job to delete.
curl -X DELETE \
https://api.catsone.com/v3/jobs/4774 \
-H 'authorization: Token <Your API Key>'
List all pipelines associated with a job.
required
string
The ID of the job to return pipelines for.
required
string
The current page number of pipelines to return.
required
string
The number of pipelines to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/1612/pipelines \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 643,
"_links": {...},
"_embedded": {
"pipelines": [
{
"id": 3498,
"candidate_id": 982,
"job_id": 4487,
"rating": 0,
"workflow_id": 7843,
"status_id": 1048,
"date_created": "2022-03-06T02:02:58.136Z",
"date_modified": "2022-09-06T01:22:40.373Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the job to fetch tasks concerning.
required
string
The current page number of tasks to return.
required
string
The number of task items to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/5804/tasks \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 250,
"_links": {...},
"_embedded": {
"tasks": [
{
"id": 3609,
"data_item": {
"id": 8073,
"type": "job"
},
"entered_by_id": 9529,
"assigned_to_id": 4163,
"description": "Ea est exercitationem quae eos eum laborum qui ipsa.",
"priority": 2,
"date_due": "2022-09-15T10:08:33.453Z",
"is_completed": true,
"date_completed": "2022-05-15T17:23:29.090Z",
"date_created": "2022-05-12T07:03:18.562Z",
"date_updated": "2022-05-03T01:34:06.564Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The string to search within jobs for.
required
string
The current page number of jobs to return.
required
string
The number of jobs to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/search \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 927,
"_links": {...},
"_embedded": {
"jobs": [
{
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This section describes the filters and fields that can be used to filter search results for this endpoint. The example given is the most simple way to pass a filter into the call. For a more in-depth explanation of boolean filtering, consult the section near the top of this page dealing with filtering.
The following are all the Job fields that can currently be filtered on, and which filters can be used on each:
`id` - greater_than, less_than, between, exactly, is_empty
`title` - contains, exactly, is_empty
`location.city` - contains, exactly, is_empty
`location.state` - contains, exactly, is_empty
`location.postal_code` - geo_distance, contains, exactly, is_empty
`country_code` - contains, exactly, is_empty
`description` - contains, exactly, is_empty
`notes` - contains, exactly, is_empty
`recruiter_id` - greater_than, less_than, between, exactly, is_empty
`owner_id` - greater_than, less_than, between, exactly, is_empty
`is_hot` - exactly, is_empty
`start_date` - greater_than, less_than, between, is_empty
`salary` - contains, exactly, is_empty
`duration` - contains, exactly, is_empty
`is_published` - exactly
`external_id` - contains, exactly, is_empty
`company_id` - greater_than, less_than, between, exactly, is_empty
`status_id` - greater_than, less_than, between, exactly, is_empty
`date_created` - greater_than, less_than, between, is_empty
`date_modified` - greater_than, less_than, between, is_empty
required
string
The optional string to search within jobs for.
required
string
The current page number of jobs to return.
required
string
The number of jobs to return per page.
required
string
The field to filter on. See the above list to determine which fields can be filtered.
required
string
The filter to use. See the above list to determine which fields allow what filters.
required
string
The value to filter by. Different filters take different value types (string, array, int). See the section in the introduction to see what values each filter accepts.
curl -X POST \
https://api.catsone.com/v3/jobs/search \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
{
"count": 25,
"total": 927,
"_links": {...},
"_embedded": {
"jobs": [
{
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
List all custom field definitions associated with the job data item type. Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
or number
.
required
string
The current page number of custom field definitions to return.
required
string
The number of custom field definitions to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 603,
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 832,
"data_item_type": "job",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
},
{...}
]
}
}
Returned field type will always be one of text
, textarea
, checkbox
, date
, dropdown
, radio
, checkboxes
, user
or number
.
required
string
The ID of the custom field definition to return.
curl -X GET \
https://api.catsone.com/v3/jobs/custom_fields/832 \
-H 'authorization: Token <Your API Key>'
{
"id": 832,
"data_item_type": "job",
"name": "Favorite Color",
"comment": "",
"field": {
"type": "text"
}
}
List all custom field values associated with a job. This returns the values of all custom fields for the job
data
item type for a single job. See the Custom Fields documentation for information on retrieving custom
field definitions.
required
string
The ID of the job to return custom fields for.
required
string
The current page number of custom fields to return.
required
string
The number of custom fields to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/7838/custom_fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": "764",
"_links": {...},
"_embedded": {
"custom_fields": [
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Get a single custom field value for a job.
required
string
The ID of the job that the custom field belongs to.
required
string
The ID of the custom field to return.
curl -X GET \
https://api.catsone.com/v3/jobs/1404/custom_fields/7383 \
-H 'authorization: Token <Your API Key>'
{
"id": 2276,
"value": "kailee",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the job that the custom field belongs to.
required
string
The ID of the custom field to update.
required
string
curl -X PUT \
https://api.catsone.com/v3/jobs/7189/custom_fields/9797 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"fredy"}'
required
string
The current page number of statuses to return.
required
string
The number of statuses to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/statuses \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 418,
"_links": {...},
"_embedded": {
"statuses": [
{
"id": 8486,
"title": "Active",
"mapping": 0,
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
},
{...}
]
}
}
required
string
The ID of the status to return.
curl -X GET \
https://api.catsone.com/v3/jobs/statuses/8486 \
-H 'authorization: Token <Your API Key>'
{
"id": 8486,
"title": "Active",
"mapping": 0,
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
}
required
string
The ID of the job that the status is being attached to.
required
number
The ID of the status to attach.
array
An array of objects each containing the ID of an attached trigger and a boolean representing whether or not to fire the trigger.
If the triggers
parameter is not set, all required triggers will be fired as well as all triggers that are marked as optional and on by default. Optional triggers that are off by default will not fire.
If the triggers
parameter is specified, all triggers that are attached to the status must be included in the array and the API will make no assumptions about which triggers to fire.
Example:
[
{
"id": <trigger ID>,
"fire": <boolean>
}
]
curl -X POST \
https://api.catsone.com/v3/jobs/9879/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":466,"triggers":[{"id":5728,"fire":false}]}'
required
string
The ID of the candidate to return attachments for.
required
string
The current page number of attachments to return.
required
string
The number of attachments to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/1058/attachments \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 325,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 9981,
"filename": "readme.txt",
"is_resume": false,
"size": "",
"version": "",
"data_item": {
"id": 7554,
"type": "candidate"
}
},
{...}
]
}
}
required
string
The ID of the job that the attachment is being attached to.
required
string
The name to save the file being uploaded as.
curl -X POST \
https://api.catsone.com/v3/jobs/6006/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
required
string
The current page number of lists to return.
required
string
The number of lists to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/lists \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 375,
"_links": {...},
"_embedded": {
"lists": [
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the job list to return.
curl -X GET \
https://api.catsone.com/v3/jobs/lists/3198 \
-H 'authorization: Token <Your API Key>'
{
"id": 2546,
"name": "facilis",
"notes": "Alias mollitia consectetur perspiciatis nisi.",
"date_created": "2022-09-29T16:08:44.771Z",
"date_modified": "2022-11-11T11:51:09.991Z",
"_links": {...},
"_embedded": {...}
}
required
string
string
curl -X POST \
https://api.catsone.com/v3/jobs/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"sint","notes":"Enim a explicabo dolor."}'
required
string
The ID of the job list to delete.
curl -X DELETE \
https://api.catsone.com/v3/jobs/lists/8747 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the job list to return items for.
required
string
The current page number of list items to return.
required
string
The number of list items to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/lists/4501/items \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 221,
"_links": {...},
"_embedded": {
"items": [
{
"id": 4823,
"date_created": "2022-10-23T19:41:08.394Z",
"job_id": 2903,
"_links": {...},
"_embedded": {
"job": {
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
}
}
},
{...}
]
}
}
required
string
The ID of the job list the item belongs to.
required
string
The ID of the job list item to return.
curl -X GET \
https://api.catsone.com/v3/jobs/lists/3438/items/723 \
-H 'authorization: Token <Your API Key>'
{
"id": 4823,
"date_created": "2022-10-23T19:41:08.394Z",
"job_id": 2903,
"_links": {...},
"_embedded": {
"job": {
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
}
}
}
Creating job list items attaches the specified jobs to a list.
required
string
The ID of the job list.
array
curl -X POST \
https://api.catsone.com/v3/jobs/lists/2165/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"job_id":389}]}'
Deleting a job list item removes a job from a list.
required
string
The ID of the job list.
required
string
The ID of the list item to delete.
curl -X DELETE \
https://api.catsone.com/v3/jobs/lists/173/items/8018 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the job to return applications for.
required
string
The current page number of contacts to return.
required
string
The number of contacts to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/9560/applications \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 395,
"_links": {...},
"_embedded": {
"applications": [
{
"id": 3846,
"description": "Eos dolorum sapiente et nulla amet quas quia.",
"header": "Maiores officia itaque et perferendis est perspiciatis qui similique.",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the job application.
required
string
The current page number of contacts to return.
required
string
The number of contacts to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/applications/8785 \
-H 'authorization: Token <Your API Key>'
{
"id": 3846,
"description": "Eos dolorum sapiente et nulla amet quas quia.",
"header": "Maiores officia itaque et perferendis est perspiciatis qui similique.",
"_links": {...},
"_embedded": {...}
}
required
string
The ID of the job application.
required
string
The current page number of contacts to return.
required
string
The number of contacts to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/applications/6142/fields \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 524,
"_links": {...},
"_embedded": {
"applications": [
{
"id": 638,
"title": "Cumque dolores voluptatum.",
"position": 0,
"type": "text",
"answers": [],
"is_required": false,
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the job to return tags for.
required
string
The current page number of tags to return.
required
string
The number of tags to return per page.
curl -X GET \
https://api.catsone.com/v3/jobs/252/tags \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 629,
"_links": {...},
"_embedded": {
"tags": [
{
"id": 4794,
"parent_id": 2791,
"title": "My Cool Tag Name",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This will replace all tags on the job with the tags specified in this call. To remove all tags from an item, send an empty tag array.
required
string
The ID of the job to replace tags on.
array
curl -X POST \
https://api.catsone.com/v3/jobs/1635/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
This will not delete any existing tags on the candidate.
required
string
The ID of the job to attach tags to.
array
curl -X PUT \
https://api.catsone.com/v3/jobs/3022/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":9068}]}'
Detaches an individual tag from the job.
required
string
The ID of the job to detach the tag from.
required
string
The ID of the tag to detach.
curl -X DELETE \
https://api.catsone.com/v3/jobs/1359/tags/5369 \
-H 'authorization: Token <Your API Key>'
required
string
The current page number of pipelines to return.
required
string
The number of pipelines to return per page.
curl -X GET \
https://api.catsone.com/v3/pipelines \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 643,
"_links": {...},
"_embedded": {
"pipelines": [
{
"id": 3498,
"candidate_id": 982,
"job_id": 4487,
"rating": 0,
"workflow_id": 7843,
"status_id": 1048,
"date_created": "2022-03-06T02:02:58.136Z",
"date_modified": "2022-09-06T01:22:40.373Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the pipeline to return.
curl -X GET \
https://api.catsone.com/v3/pipelines/3498 \
-H 'authorization: Token <Your API Key>'
{
"id": 3498,
"candidate_id": 982,
"job_id": 4487,
"rating": 0,
"workflow_id": 7843,
"status_id": 1048,
"date_created": "2022-03-06T02:02:58.136Z",
"date_modified": "2022-09-06T01:22:40.373Z",
"_links": {...},
"_embedded": {...}
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
required
string
Whether a corresponding activity should be created automatically. This mimics what happens when a pipeline is created from the CATS UI. Defaults to false.
required
number
The ID of the candidate that this pipeline is regarding.
required
number
The ID of the job order that this pipeline is for.
number
The candidate's rating (0-5) for this job order pipeline.
curl -X POST \
https://api.catsone.com/v3/pipelines \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"candidate_id":4320,"job_id":7242,"rating":4}'
required
string
The ID of the pipeline to update.
number
The candidate's rating (0-5) for this job order pipeline.
curl -X PUT \
https://api.catsone.com/v3/pipelines/5715 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"rating":5}'
required
string
Whether a corresponding activity should be created automatically. This mimics what happens when a pipeline is created from the CATS UI. Defaults to false.
required
string
The ID of the pipeline to delete.
curl -X DELETE \
https://api.catsone.com/v3/pipelines/6255 \
-H 'authorization: Token <Your API Key>'
This section describes the filters and fields that can be used to filter search results for this endpoint. The example given is the most simple way to pass a filter into the call. For a more in-depth explanation of boolean filtering, consult the section near the top of this page dealing with filtering.
The following are all the Pipeline fields that can currently be filtered on, and which filters can be used on each:
`id` - greater_than, less_than, between, exactly, is_empty
`candidate_id` - greater_than, less_than, between, exactly, is_empty
`job_id` - greater_than, less_than, between, exactly, is_empty
`status_id` - greater_than, less_than, between, exactly, is_empty
`rating` - greater_than, less_than, between, exactly, is_empty
`date_created` - greater_than, less_than, between, is_empty
`date_modified` - greater_than, less_than, between, is_empty
required
string
The current page number of pipelines to return.
required
string
The number of pipelines to return per page.
required
string
The field to filter on. See the above list to determine which fields can be filtered.
required
string
The filter to use. See the above list to determine which fields allow what filters.
required
string
The value to filter by. Different filters take different value types (string, array, int). See the section in the introduction to see what values each filter accepts.
curl -X POST \
https://api.catsone.com/v3/pipelines/search \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
{
"count": 25,
"total": 643,
"_links": {...},
"_embedded": {
"pipelines": [
{
"id": 3498,
"candidate_id": 982,
"job_id": 4487,
"rating": 0,
"workflow_id": 7843,
"status_id": 1048,
"date_created": "2022-03-06T02:02:58.136Z",
"date_modified": "2022-09-06T01:22:40.373Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The current page number of workflows to return.
required
string
The number of workflows to return per page.
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows \
-H 'authorization: Token <Your API Key>'
{
"count": 10,
"total": 10,
"_links": {...},
"_embedded": {
"workflows": [
{
"id": 7343,
"title": "Iusto ipsam quo incidunt enim dicta et ipsum dicta consectetur.",
"is_default": false,
"date_modified": "2022-02-20T04:04:01.451Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the workflow to return.
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows/7584 \
-H 'authorization: Token <Your API Key>'
{
"id": 7343,
"title": "Iusto ipsam quo incidunt enim dicta et ipsum dicta consectetur.",
"is_default": false,
"date_modified": "2022-02-20T04:04:01.451Z",
"_links": {...},
"_embedded": {...}
}
required
string
The current page number of statuses to return.
required
string
The number of statuses to return per page.
required
string
The ID of the workflow to return statuses for.
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows/7584/statuses \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 209,
"_links": {...},
"_embedded": {
"statuses": [
{
"id": 8486,
"title": "Offered",
"mapping": 0,
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
},
{...}
]
}
}
required
string
The ID of the workflow to return statuses for.
required
string
The ID of the status to return.
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows/7584/statuses/8486 \
-H 'authorization: Token <Your API Key>'
{
"id": 8486,
"title": "Offered",
"mapping": 0,
"prerequisites": [
{
"id": 1452
}
],
"triggers": [
{
"id": 6580
}
],
"_links": {...}
}
required
string
The ID of the pipeline to fetch status history from
curl -X GET \
https://api.catsone.com/v3/pipelines/9747/statuses \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 104,
"_links": {...},
"_embedded": {
"statuses": [
{
"id": 8486,
"from_id": 8675,
"workflow_id": 2904,
"title": "Lead",
"mapping": "lead",
"is_current": true,
"user_id": 7343,
"date_changed": "2022-10-27T08:36:14.924Z",
"_links": {...}
},
{...}
]
}
}
required
string
The ID of the pipeline that the status is being attached to.
required
string
Whether a corresponding activity should be created automatically. This mimics what happens when a pipeline is created from the CATS UI. Defaults to false.
required
number
The ID of the status to attach.
array
An array of objects each containing the ID of an attached trigger and a boolean representing whether or not to fire the trigger.
If the triggers
parameter is not set, all required triggers will be fired as well as all triggers that are marked as optional and on by default. Optional triggers that are off by default will not fire.
If the triggers
parameter is specified, all triggers that are attached to the status must be included in the array and the API will make no assumptions about which triggers to fire.
Example:
[
{
"id": <trigger ID>,
"fire": <boolean>
}
]
curl -X POST \
https://api.catsone.com/v3/pipelines/5930/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":466,"triggers":[{"id":5728,"fire":false}]}'
This endpoint returns basic portal metadata. In addition to the fields shown in the example below, within the _links
object you will find portal_url
which has a direct link to your portal site.
required
string
The current page number of portals to return.
required
string
The number of portals to return per page.
curl -X GET \
https://api.catsone.com/v3/portals \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 349,
"_links": {...},
"_embedded": {
"activities": [
{
"id": 6306,
"name": "Maxime quisquam debitis porro.",
"date_created": "2022-12-22T19:47:26.884Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
This endpoint returns basic portal metadata. In addition to the fields shown in the example below, within the _links
object you will find portal_url
which has a direct link to your portal site.
required
string
The ID of the portal to return.
curl -X GET \
https://api.catsone.com/v3/portals/6306 \
-H 'authorization: Token <Your API Key>'
{
"id": 6306,
"name": "Maxime quisquam debitis porro.",
"date_created": "2022-12-22T19:47:26.884Z",
"_links": {...},
"_embedded": {...}
}
This endpoint returns jobs that have been published to a particular portal. In addition to the fields shown in the
example below, within the _links
object you will find job_url
which has a direct link to the job on your portal.
required
string
The ID of the portal to return jobs for.
required
string
The current page number of jobs to return.
required
string
The number of jobs to return per page.
curl -X GET \
https://api.catsone.com/v3/portals/6306/jobs \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 927,
"_links": {...},
"_embedded": {
"jobs": [
{
"id": 839,
"title": "Investor Directives Consultant",
"location": {
"city": "Winonafurt",
"state": "ND",
"postal_code": "50507-9514"
},
"country_code": "US",
"description": "Sed nihil omnis repellendus eos. Quis voluptate ut aperiam aliquam voluptates asperiores voluptas iusto. Et veniam ratione. Est eligendi eius qui velit nihil impedit et et neque.",
"notes": "Dolores amet alias qui ut quidem.",
"recruiter_id": 2228,
"owner_id": 9403,
"category": null,
"is_hot": true,
"start_date": "2022-04-19T08:45:18.134Z",
"salary": null,
"max_rate": null,
"duration": "",
"external_id": null,
"company_id": 5617,
"department_id": 2985,
"status_id": 5697,
"workflow_id": 2427,
"is_published": false,
"portal_hidden": true,
"user_groups": [],
"date_created": "2022-08-17T07:59:20.252Z",
"date_modified": "2022-09-03T14:46:13.301Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
Using this endpoint, you can submit a new application for a specific job on a portal.
The body of this request should have a fields key with an array of job application field objects as its value. To determine which fields need to be included in a call, see job application and job application fields. Each object can/should have the following keys/values:
id: (integer, required) All fields will have an id.
value: (string|boolean|object|null, required) All fields will also have a value. Text and text-like fields accept strings. File fields should be a base64 encoded string of your file as the value. Others only accept objects or booleans. See the examples below for all the different cases. You can find out what type a field is by fetching that field from job application fields.
filename: (string) This field is only used/required for file fields. Since files are passed at 64bit encoded strings with no name, you must pass a filename here.
See below for a full example with all field types.
required
string
The ID of the portal the job being submitted to is on.
required
string
The ID of the job the application is being submitted for.
array
An example with all fields types:
{
"fields": [
{
/* file */
"id": 523423,
"value": "SGVsbG8gV29ybGQ=",
"filename": "helloworld.txt"
},
{
/* text */
"id": 523591,
"value": "James"
},
{
/* multiline */
"id": 524022
"value": "line 1\r\nline 2"
},
{
/* checkbox */
"id": 524156
"value": true
},
{
/* checkboxes */
"id": 524221
"value": {
"3251": true,
"3991": true
}
},
{
/* radio/select */
"id": 524221
"value": {
"4126": true
}
}
],
"source": "Google"
}
string
If the applicant is brand new to the system, what you provide in the source field will be set as their source. If they are not new to the system, their existing source will NOT be overwritten. If source is not provided it defaults to "Career Portal".
curl -X POST \
https://api.catsone.com/v3/portals/6600/jobs/1019 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"fields":[{"id":5933,"value":"quasi"}],"source":"Google"}'
This endpoint allows you to publish a job to a portal. This will not publish the job to any third-party boards.
Note: While no data needs to be passed into the body of this call, we do require a properly formatted json body on all PUT
endpoints, so any calls to this endpoint should include an empty json object, e.g. {}
.
required
string
The ID of the portal the job being submitted to is on.
required
string
The ID of the job the application is being submitted for.
curl -X PUT \
https://api.catsone.com/v3/portals/2252/jobs/7377 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{}'
This endpoint allows you to remove a job from a portal
required
string
The ID of the portal the job being submitted to is on.
required
string
The ID of the job the application is being submitted for.
curl -X DELETE \
https://api.catsone.com/v3/portals/7583/jobs/8853 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the portal to return registration application for.
curl -X GET \
https://api.catsone.com/v3/portals/6306/registration \
-H 'authorization: Token <Your API Key>'
{
"id": 3846,
"description": "Eos dolorum sapiente et nulla amet quas quia.",
"header": "Maiores officia itaque et perferendis est perspiciatis qui similique.",
"_links": {...},
"_embedded": {...}
}
Using this endpoint, you can submit a portal registration application.
The body of this request follows the same structure as the normal submit endpoint but with the portal registration application instead of a job application.
required
string
The ID of the portal being submitted to.
array
An example with all fields types:
{
"fields": [
{
/* file */
"id": 523423,
"value": "SGVsbG8gV29ybGQ=",
"filename": "helloworld.txt"
},
{
/* text */
"id": 523591,
"value": "James"
},
{
/* multiline */
"id": 524022
"value": "line 1\r\nline 2"
},
{
/* checkbox */
"id": 524156
"value": true
},
{
/* checkboxes */
"id": 524221
"value": {
"3251": true,
"3991": true
}
},
{
/* radio/select */
"id": 524221
"value": {
"4126": true
}
}
],
"source": "Google"
}
string
If the applicant is brand new to the system, what you provide in the source field will be set as their source. If they are not new to the system, their existing source will NOT be overwritten. If source is not provided it defaults to "Career Portal".
curl -X POST \
https://api.catsone.com/v3/portals/6306/registration \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"fields":[{"id":5933,"value":"quasi"}],"source":"Google"}'
Get information the site associated with the API token being used.
curl -X GET \
https://api.catsone.com/v3/site \
-H 'authorization: Token <Your API Key>'
{
"id": 9926,
"mode": "recruiter",
"subdomain": "kitten",
"_links": {...},
"_embedded": {...}
}
required
string
The current page number of tags to return.
required
string
The number of tags to return per page.
curl -X GET \
https://api.catsone.com/v3/tags \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 629,
"_links": {...},
"_embedded": {
"tags": [
{
"id": 4794,
"parent_id": 2791,
"title": "My Cool Tag Name",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the tag to return.
curl -X GET \
https://api.catsone.com/v3/tags/4794 \
-H 'authorization: Token <Your API Key>'
{
"id": 4794,
"parent_id": 2791,
"title": "My Cool Tag Name",
"_links": {...},
"_embedded": {...}
}
required
string
The current page number of tasks to return.
required
string
The number of tasks to return per page.
curl -X GET \
https://api.catsone.com/v3/tasks \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 231,
"_links": {...},
"_embedded": {
"tasks": [
{
"id": 3609,
"data_item": {
"id": 7451,
"type": "job"
},
"entered_by_id": 9329,
"assigned_to_id": 9627,
"description": "Eius delectus ut delectus a.",
"priority": 2,
"date_due": "2022-10-14T18:55:42.911Z",
"is_completed": true,
"date_completed": "2022-01-12T17:28:49.546Z",
"date_created": "2022-06-17T00:53:46.946Z",
"date_updated": "2022-02-14T21:11:11.763Z",
"_links": {...},
"_embedded": {...}
},
{...}
]
}
}
required
string
The ID of the task to return.
curl -X GET \
https://api.catsone.com/v3/tasks/3609 \
-H 'authorization: Token <Your API Key>'
{
"id": 3609,
"data_item": {
"id": 7451,
"type": "job"
},
"entered_by_id": 9329,
"assigned_to_id": 9627,
"description": "Eius delectus ut delectus a.",
"priority": 2,
"date_due": "2022-10-14T18:55:42.911Z",
"is_completed": true,
"date_completed": "2022-01-12T17:28:49.546Z",
"date_created": "2022-06-17T00:53:46.946Z",
"date_updated": "2022-02-14T21:11:11.763Z",
"_links": {...},
"_embedded": {...}
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
DataItem
A DataItem the object is about, or null for a general task
number
The user to assign the task to
string
number
A number 1-5, with 1 being the lowest priority
string
If null the task will be assigned ASAP as in the CATS UI
curl -X POST \
https://api.catsone.com/v3/tasks \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"data_item":{"id":7451,"type":"job"},"assigned_to_id":6889,"description":"Recusandae id nulla cum.","priority":3,"date_due":"2022-04-13T23:52:29.388Z"}'
required
string
The ID of the task to update.
number
The user to assign the task to
string
number
A number 1-5, with 1 being the lowest priority
string
If null the task will be assigned ASAP as in the CATS UI
boolean
curl -X PUT \
https://api.catsone.com/v3/tasks/9855 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"assigned_to_id":1522,"description":"Velit voluptatem doloremque esse ad eveniet.","priority":3,"date_due":"2022-10-26T04:45:22.019Z","is_completed":true}'
required
string
The ID of the task to delete.
curl -X DELETE \
https://api.catsone.com/v3/tasks/9804 \
-H 'authorization: Token <Your API Key>'
required
string
The current page number of triggers to return.
required
string
The number of triggers to return per page.
curl -X GET \
https://api.catsone.com/v3/triggers \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 252,
"_links": {...},
"_embedded": {
"triggers": [
{
"id": 6391
},
{...}
]
}
}
required
string
The ID of the trigger to return.
curl -X GET \
https://api.catsone.com/v3/triggers/6391 \
-H 'authorization: Token <Your API Key>'
{
"id": 6391
}
required
string
The current page number of users to return.
required
string
The number of users to return per page.
curl -X GET \
https://api.catsone.com/v3/users \
-H 'authorization: Token <Your API Key>'
{
"count": 10,
"total": 10,
"_links": {...},
"_embedded": {
"users": [
{
"id": 7343,
"username": "Efrain38@hotmail.com",
"first_name": "Jayson",
"last_name": "Mann",
"title": "Direct Configuration Producer",
"access_level: `add_edit_delete`": "",
"_links": {...}
},
{...}
]
}
}
required
string
The ID of the user to return.
curl -X GET \
https://api.catsone.com/v3/users/7343 \
-H 'authorization: Token <Your API Key>'
{
"id": 7343,
"username": "Efrain38@hotmail.com",
"first_name": "Jayson",
"last_name": "Mann",
"title": "Direct Configuration Producer",
"access_level: `add_edit_delete`": "",
"_links": {...}
}
Webhooks can be set up to fire for many events (see below). The returned Hal object
will contain basic information about the event as well as ebed copies of all relevant resources. For example,
a candidate.status_changed
webhook would look like the following:
{
"event": "candidate.status_changed",
"candidate_id": 532443,
"previous_status_id": 2236901,
"new_status_id": 2236978,
"_embedded": {...}
}
The webhook will continue to fire every time the event occurs until it is deleted or the target url returns
a 410
http status code.
required
string
The current page number of webhooks to return.
required
string
The number of webhooks to return per page.
curl -X GET \
https://api.catsone.com/v3/webhooks \
-H 'authorization: Token <Your API Key>'
{
"count": 25,
"total": 938,
"_links": {...},
"_embedded": {
"webhooks": [
{
"id": 5114,
"event": "candidate.created",
"target_url": "https://mmountain.herokuapp.com/kAa5An56ew"
},
{...}
]
}
}
required
string
The ID of the webhook to return.
curl -X GET \
https://api.catsone.com/v3/webhooks/5114 \
-H 'authorization: Token <Your API Key>'
{
"id": 5114,
"event": "candidate.created",
"target_url": "https://mmountain.herokuapp.com/kAa5An56ew"
}
As with all POST endpoints, a location header will be returned with a url to the newly created resource.
required
array
An array of one or more of the following event types: candidate.created
, job.created
, contact.created
, company.created
, activity.created
, user.created
, pipeline.created
, candidate.updated
, job.updated
, contact.updated
, company.updated
, activity.updated
, user.updated
, candidate.deleted
, job.deleted
, contact.deleted
, company.deleted
, activity.deleted
, user.deleted
, pipeline.deleted
, job.status_changed
, contact.status_changed
, company.status_changed
, pipeline.status_changed
required
string
URL to post the record to once the event is triggered.
optional
string
Highly Recommended. If provided, you can use this string to verify that authenticity of webhooks sent to target_url
. All webhooks you subscribe to you will send a X-Signature
header. To determine whether the X-Signature
header is valid take the body of the webhook response, append the value of the X-Request-Id
header to it, and then generate a HMAC-SHA256
hash of it using your secret as a key. That final result should match the hash found in the X-Signature
header. Here are two examples of the verification process in PHP and Python 3:
$secret = 'yourSecretHere';
$webhookBody = '{}';
// `X-Request-Id` header
$requestId = '5d6ce3f9-cce8-4b5b-a26e-396a6161eb99';
// `X-Signature` header
$signature = 'HMAC-SHA256 affc8d589f36580daa0d587ac0b314c123b59322cf4d018661e0a403cc76391f';
$hash = hash_hmac('sha256', $requestBody . $requestId, $secret, false);
if ($signature !== 'HMAC-SHA256 ' . $hash) {
// Reject it
}
curl -X POST \
https://api.catsone.com/v3/webhooks \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"events":["candidate.created"],"target_url":"https://mmountain.herokuapp.com/kAa5An56ew","secret":"kAehRa5An4sndfuJ7i5sdf6e00wGP"}'
A webhook will also be deleted if target_url responds with status code 410.
required
string
The ID of the webhook to delete.
curl -X DELETE \
https://api.catsone.com/v3/webhooks/3642 \
-H 'authorization: Token <Your API Key>'
required
string
The ID of the work history to return.
curl -X GET \
https://api.catsone.com/v3/work_history/9528 \
-H 'authorization: Token <Your API Key>'
{
"id": 5299,
"title": "Principal Configuration Assistant",
"candidate_id": 8736,
"employer": {
"linked": false,
"name": "Grant Group",
"location": {
"city": "Lake Simeonport",
"state": "NV"
}
},
"supervisor": {
"linked": false,
"name": "Octavia",
"phone": "(400) 379-2500"
},
"is_verified": false,
"is_current": false,
"start_date": "2022-02-20T22:28:24.180Z",
"end_date": "2022-03-19T05:10:17.283Z",
"reason_for_leaving": "Voluptatem tenetur enim nostrum dolores laborum unde aut repellat dignissimos."
}
required
string
The ID of the work history to update.
required
string
required
object
An object containing the employer information for a work history item with one of the following structures:
{
"linked": false,
"name": "<employer name>",
"location": {
"city": "<employer city>",
"state": "<employer state>"
}
}
or
{
"linked": true,
"company_id": 465
}
Both linked
and name
are required fields within the first object, and linked
and company_id
are required in the second object.
object
An object containing the supervisor information for a work history item with one of the following structures:
{
"linked": false,
"name": "<supervisor name>",
"phone": "<supervisor phone number>"
}
or
{
"linked": true,
"contact_id": 6864
}
boolean
string
If this is set to true
, both end_date
and reason_for_leaving
will be ignored.
string
string
string
curl -X PUT \
https://api.catsone.com/v3/work_history/9528 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Forward Integration Assistant","employer":{"linked":false,"name":"Satterfield, Franecki and Zulauf","location":{"city":"East Angeline","state":"IN"}},"supervisor":{"linked":false,"name":"Donny","phone":"(619) 861-7766"},"is_verified":true,"is_current":"false","start_date":"2022-05-14T00:03:00.437Z","end_date":"2022-02-12T21:40:21.527Z","reason_for_leaving":"Sunt et porro aut asperiores voluptatibus molestiae repellendus ut."}'
required
string
The ID of the work history to delete.
curl -X DELETE \
https://api.catsone.com/v3/work_history/1110 \
-H 'authorization: Token <Your API Key>'