CATS API v3

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.

Host

The host for API requests is https://api.catsone.com/v3.

All API requests must be made over HTTPS. HTTP is not supported.

Authentication

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>

Input/output format

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.

Date formats

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

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

HAL

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": 9774,
  "first_name": "Rylee",
  "last_name": "Carter",
  "owner_id": 2742,
  ...
  "_links": {
    "self": {
      "href": "/candidates/9774"
    },
    "custom_fields": {
      "href": "/candidates/9774/custom_fields"
    },
    "owner": {
      "href": "/users/2742"
    },
    "activities": {
      "href": "/candidates/9774/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": "korbin",
      ...
    },
    {...}
  ]
}

In this example, you can access the custom fields attached to the candidate without needing to make a separate API call.

Pagination

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

Common data types

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": 8523,
  "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.

Search filters

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

Rate limiting

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>

Webhooks

You can subscribe to webhooks via the API or via the CATS Administrative UI. A typical webhook will look like the following:
{
    "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.

Changelog

View the changelog for updates and changes to the API.

Mailing List

Sign up to be notified about major changes and updates to the CATS API

* indicates required

Activities

GET /activities{?page,per_page}

List all activities

Parameters
page

required

string

The current page number of activities to return.

per_page

required

string

The number of activities to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 969,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9926,
        "data_item": {
          "id": 5621,
          "type": "job"
        },
        "date": "2022-05-01T03:37:28.445Z",
        "regarding_id": 3399,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 3839,
        "date_created": "2022-06-27T03:56:11.234Z",
        "date_modified": "2022-07-10T15:56:04.802Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /activities/{id}

Get an activity

Parameters
id

required

string

The ID of the activity to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/activities/9926 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9926,
  "data_item": {
    "id": 5621,
    "type": "job"
  },
  "date": "2022-05-01T03:37:28.445Z",
  "regarding_id": 3399,
  "type": "call_lvm",
  "notes": "Left voicemail.",
  "annotation": "General",
  "entered_by_id": 3839,
  "date_created": "2022-06-27T03:56:11.234Z",
  "date_modified": "2022-07-10T15:56:04.802Z",
  "_links": {...},
  "_embedded": {...}
}

PUT /activities/{id}

Update an activity

Parameters
id

required

string

The ID of the activity to update.

Body Parameters
type

required

string

One of the following activity types: email, meeting, call_talked, call_lvm, call_missed, text_message or other.

regarding_id

number

The ID of the job order that this activity is regarding. Leave null for a general activity.

notes

string

date

string

The datetime the activity took place. If not specified it defaults to the current date and time.

Example Request
curl -X PUT \
https://api.catsone.com/v3/activities/3823 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":3172,"notes":"Sequi velit mollitia aut magni iure.","date":"2022-05-18T10:53:54.025Z"}'
Example Response

DELETE /activities/{id}

Delete an activity

Parameters
id

required

string

The ID of the activity to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/activities/42 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /activities/search{?query,page,per_page}

Search activities

Parameters
query

required

string

The string to search within activities for.

page

required

string

The current page number of activities to return.

per_page

required

string

The number of activities to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/activities/search \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 969,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9926,
        "data_item": {
          "id": 5621,
          "type": "job"
        },
        "date": "2022-05-01T03:37:28.445Z",
        "regarding_id": 3399,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 3839,
        "date_created": "2022-06-27T03:56:11.234Z",
        "date_modified": "2022-07-10T15:56:04.802Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /activities/search{?query,page,per_page}

Filter activities

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

Parameters
query

required

string

The optional string to search within activities for.

page

required

string

The current page number of activities to return.

per_page

required

string

The number of activities to return per page.

Body Parameters
field

required

string

The field to filter on. See the above list to determine which fields can be filtered.

filter

required

string

The filter to use. See the above list to determine which fields allow what filters.

value

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.

Example Request
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"}'
Example Response
{
  "count": 25,
  "total": 969,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9926,
        "data_item": {
          "id": 5621,
          "type": "job"
        },
        "date": "2022-05-01T03:37:28.445Z",
        "regarding_id": 3399,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 3839,
        "date_created": "2022-06-27T03:56:11.234Z",
        "date_modified": "2022-07-10T15:56:04.802Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

Attachments

GET /attachments/{id}

Get an attachment

Parameters
id

required

string

The ID of the attachment to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/attachments/267 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 267,
  "filename": "readme.txt",
  "is_resume": false,
  "size": "",
  "version": "",
  "data_item": {
    "id": 5007,
    "type": "candidate"
  }
}

DELETE /attachments/{id}

Delete an attachment

Parameters
id

required

string

The ID of the attachment to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/attachments/655 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /attachments/{id}/download

Download an attachment

Parameters
id

required

string

The ID of the attachment to download.

Example Request
curl -X GET \
https://api.catsone.com/v3/attachments/267/download \
-H 'authorization: Token <Your API Key>'
Example Response

POST /attachments/parse

Parse a resume

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.

Example Request
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
Example Response
{
  "first_name": "Dallas",
  "middle_name": "Kurtis",
  "last_name": "Welch",
  "title": "Regional Integration Specialist",
  "emails": {
    "primary": "Casandra.Mohr@hotmail.com"
  },
  "address": {
    "street": "22840 Maxine Alley",
    "city": "New Jarvis",
    "state": "AL",
    "postal_code": "09774"
  },
  "country_code": "US",
  "social_media_urls": [],
  "phones": {
    "home": "(748) 638-2739",
    "cell": "(972) 373-7143",
    "work": "(206) 994-5786"
  },
  "current_employer": "Becker, Davis and Rodriguez",
  "source": "Google"
}

Backups

GET /backups{?page,per_page}

List all backups

Parameters
page

required

string

The current page number of backups to return.

per_page

required

string

The number of backups to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/backups \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 412,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9976,
        "status": "expired",
        "url": "http://llewellyn.info",
        "file_size": 294516033,
        "started_by_id": 5118,
        "date_created": "2022-11-20T13:22:59.647Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /backups/{id}

Get a backup

Parameters
id

required

string

The ID of the backup to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/backups/2369 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9976,
  "status": "expired",
  "url": "http://llewellyn.info",
  "file_size": 294516033,
  "started_by_id": 5118,
  "date_created": "2022-11-20T13:22:59.647Z",
  "_links": {...},
  "_embedded": {...}
}

POST /backups

Create a backup

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.

Body Parameters
include_attachments

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.

include_emails

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.

Example Request
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}'
Example Response

Candidates

GET /candidates{?page,per_page}

List all candidates

Parameters
page

required

string

The current page number of candidates to return.

per_page

required

string

The number of candidates to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 817,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 4552,
        "first_name": "Fay",
        "middle_name": "Barton",
        "last_name": "Kunze",
        "title": "Customer Marketing Specialist",
        "emails": {
          "primary": "Ezra_Tremblay88@yahoo.com",
          "secondary": "Ozella_Hamill25@yahoo.com"
        },
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "social_media_urls": [],
        "website": "https://layne.name",
        "best_time_to_call": "After 5pm",
        "current_employer": "Sawayn - Hyatt",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": false,
        "key_skills": "Programming, management, fishing",
        "notes": "Aliquid maiores dolores fugit sunt aut est.",
        "source": "Google",
        "is_hot": false,
        "is_active": false,
        "is_registered": false,
        "contact_id": 7241,
        "owner_id": 2658,
        "entered_by_id": 5798,
        "date_created": "2022-07-26T22:15:21.356Z",
        "date_modified": "2022-04-04T13:35:02.823Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{id}

Get a candidate

Parameters
id

required

string

The ID of the candidate to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/4552 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4552,
  "first_name": "Fay",
  "middle_name": "Barton",
  "last_name": "Kunze",
  "title": "Customer Marketing Specialist",
  "emails": {
    "primary": "Ezra_Tremblay88@yahoo.com",
    "secondary": "Ozella_Hamill25@yahoo.com"
  },
  "address": {
    "street": "22840 Maxine Alley",
    "city": "New Jarvis",
    "state": "AL",
    "postal_code": "09774"
  },
  "country_code": "US",
  "social_media_urls": [],
  "website": "https://layne.name",
  "best_time_to_call": "After 5pm",
  "current_employer": "Sawayn - Hyatt",
  "date_available": "Next month",
  "current_pay": "50k",
  "desired_pay": "120k",
  "is_willing_to_relocate": false,
  "key_skills": "Programming, management, fishing",
  "notes": "Aliquid maiores dolores fugit sunt aut est.",
  "source": "Google",
  "is_hot": false,
  "is_active": false,
  "is_registered": false,
  "contact_id": 7241,
  "owner_id": 2658,
  "entered_by_id": 5798,
  "date_created": "2022-07-26T22:15:21.356Z",
  "date_modified": "2022-04-04T13:35:02.823Z",
  "_links": {...},
  "_embedded": {...}
}

POST /candidates{?check_duplicate}

Create a candidate

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Parameters
check_duplicate

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.

Body Parameters
first_name

required

string

middle_name

string

last_name

required

string

title

string

The candidate's job title.

emails

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?>"
    }
]
phones

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>",
    }
]
address

object

An object containing the address for the candidate with the following structure:

{
  "street": "<street>",
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

social_media_urls

array

website

string

best_time_to_call

string

current_employer

string

date_available

string

The date the candidate is available for an opening.

current_pay

string

desired_pay

string

is_willing_to_relocate

boolean

key_skills

string

notes

string

source

string

owner_id

number

The user id of the record owner

is_active

boolean

A flag indicating if the candidate is active.

is_hot

boolean

A flag indicating if the candidate should be marked as hot. A hot candidate is highlighted in the candidates view.

password

string

The candidate's password if they are "registering". Registered candidate can be authenticated with /candidates/authorization.

custom_fields

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>"
    }
]
work_history

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"
    }
]
Example Request
curl -X POST \
https://api.catsone.com/v3/candidates \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Easton","middle_name":"Abagail Bull","last_name":"Cartwright","title":"Senior Applications Manager","emails":[{"email":"Newell.Bins71@gmail.com","is_primary":true}],"phones":[{"number":"+16124063451","extension":"8371","type":"Mobile"}],"address":{"street":"1112 Schimmel Meadow","city":"West Howardhaven","state":"Indiana","postal_code":"65986"},"country_code":"US","social_media_urls":[],"website":"https://camylle.com","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":3023,"is_active":false,"is_hot":true,"password":"6qDvYjYJNYHKgXU","custom_fields":[{"id":5851,"value":"lorem"}],"work_history":[{"title":"Chief Markets Technician","employer":{"linked":false,"name":"Altenwerth - Kertzmann","location":{"city":"Schneiderchester","state":"MI"}},"supervisor":{"linked":false,"name":"Andrew","phone":"(509) 639-9671"},"is_verified":true,"is_current":"false","start_date":"2022-07-02T08:16:37.933Z","end_date":"2022-08-13T18:22:46.655Z","reason_for_leaving":"Eum ut ut dolorem aut et eveniet rerum."}]}'
Example Response

PUT /candidates/{id}

Update a candidate

Parameters
id

required

string

The ID of the candidate to update.

Body Parameters
first_name

required

string

middle_name

string

last_name

required

string

title

string

The candidate's job title.

address

object

An object containing the address for the candidate with the following structure:

{
  "street": "<street>",
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

social_media_urls

array

website

string

best_time_to_call

string

current_employer

string

date_available

string

The date the candidate is available for an opening.

current_pay

string

desired_pay

string

is_willing_to_relocate

boolean

key_skills

string

notes

string

source

string

owner_id

number

The user id of the record owner

is_active

boolean

A flag indicating if the candidate is active.

is_hot

boolean

A flag indicating if the candidate should be marked as hot. A hot candidate is highlighted in the candidates view.

password

string

The candidate's password if they are "registering". Registered candidate can be authenticated with /candidates/authorization.

custom_fields

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>"
    }
]
Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/9061 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Webster","middle_name":"Schuyler Bull","last_name":"West","title":"Internal Infrastructure Director","address":{"street":"69175 Wolff Roads","city":"Douglasbury","state":"West Virginia","postal_code":"84421-0642"},"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":6607,"is_active":false,"is_hot":true,"password":"AMBqrnmYFptT2_M","custom_fields":[{"id":5851,"value":"lorem"}]}'
Example Response

DELETE /candidates/{id}

Delete a candidate

Parameters
id

required

string

The ID of the candidate to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/7097 \
-H 'authorization: Token <Your API Key>'
Example Response

POST /candidates/authorization

Authorize a candidate

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.

Body Parameters
email

string

password

string

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/authorization \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Kaci72@gmail.com","password":"4aqSMPpeNlVzboo"}'
Example Response
{
  "id": 4552,
  "first_name": "Fay",
  "middle_name": "Barton",
  "last_name": "Kunze",
  "title": "Customer Marketing Specialist",
  "emails": {
    "primary": "Ezra_Tremblay88@yahoo.com",
    "secondary": "Ozella_Hamill25@yahoo.com"
  },
  "address": {
    "street": "22840 Maxine Alley",
    "city": "New Jarvis",
    "state": "AL",
    "postal_code": "09774"
  },
  "country_code": "US",
  "social_media_urls": [],
  "website": "https://layne.name",
  "best_time_to_call": "After 5pm",
  "current_employer": "Sawayn - Hyatt",
  "date_available": "Next month",
  "current_pay": "50k",
  "desired_pay": "120k",
  "is_willing_to_relocate": false,
  "key_skills": "Programming, management, fishing",
  "notes": "Aliquid maiores dolores fugit sunt aut est.",
  "source": "Google",
  "is_hot": false,
  "is_active": false,
  "is_registered": false,
  "contact_id": 7241,
  "owner_id": 2658,
  "entered_by_id": 5798,
  "date_created": "2022-07-26T22:15:21.356Z",
  "date_modified": "2022-04-04T13:35:02.823Z",
  "_links": {...},
  "_embedded": {...}
}

GET /candidates/{id}/pipelines{?page,per_page}

List pipelines by candidate

List all pipelines associated with a candidate.

Parameters
id

required

string

The ID of the candidate to return pipelines for.

page

required

string

The current page number of pipelines to return.

per_page

required

string

The number of pipelines to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/2381/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 275,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 313,
        "candidate_id": 9856,
        "job_id": 9974,
        "rating": 1,
        "workflow_id": 795,
        "status_id": 4781,
        "date_created": "2022-06-05T05:11:16.553Z",
        "date_modified": "2022-11-07T13:52:27.700Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{id}/tasks{?page,per_page}

List candidate tasks

Parameters
id

required

string

The ID of the candidate to fetch tasks concerning.

page

required

string

The current page number of tasks to return.

per_page

required

string

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/3637/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 984,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 8895,
        "data_item": {
          "id": 7725,
          "type": "candidate"
        },
        "entered_by_id": 7196,
        "assigned_to_id": 5001,
        "description": "Nobis dolor doloribus quia molestias hic architecto numquam.",
        "priority": 2,
        "date_due": "2022-04-30T16:22:00.300Z",
        "is_completed": true,
        "date_completed": "2022-01-13T11:38:48.933Z",
        "date_created": "2022-06-30T15:41:31.283Z",
        "date_updated": "2022-10-19T04:29:37.522Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/search{?query,page,per_page}

Search candidates

Parameters
query

required

string

The string to search within candidates for.

page

required

string

The current page number of candidates to return.

per_page

required

string

The number of candidates to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/search \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 817,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 4552,
        "first_name": "Fay",
        "middle_name": "Barton",
        "last_name": "Kunze",
        "title": "Customer Marketing Specialist",
        "emails": {
          "primary": "Ezra_Tremblay88@yahoo.com",
          "secondary": "Ozella_Hamill25@yahoo.com"
        },
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "social_media_urls": [],
        "website": "https://layne.name",
        "best_time_to_call": "After 5pm",
        "current_employer": "Sawayn - Hyatt",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": false,
        "key_skills": "Programming, management, fishing",
        "notes": "Aliquid maiores dolores fugit sunt aut est.",
        "source": "Google",
        "is_hot": false,
        "is_active": false,
        "is_registered": false,
        "contact_id": 7241,
        "owner_id": 2658,
        "entered_by_id": 5798,
        "date_created": "2022-07-26T22:15:21.356Z",
        "date_modified": "2022-04-04T13:35:02.823Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/search{?query,page,per_page}

Filter candidates

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

Parameters
query

required

string

The optional string to search within candidates for.

page

required

string

The current page number of candidates to return.

per_page

required

string

The number of candidates to return per page.

Body Parameters
field

required

string

The field to filter on. See the above list to determine which fields can be filtered.

filter

required

string

The filter to use. See the above list to determine which fields allow what filters.

value

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.

Example Request
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"}'
Example Response
{
  "count": 25,
  "total": 817,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 4552,
        "first_name": "Fay",
        "middle_name": "Barton",
        "last_name": "Kunze",
        "title": "Customer Marketing Specialist",
        "emails": {
          "primary": "Ezra_Tremblay88@yahoo.com",
          "secondary": "Ozella_Hamill25@yahoo.com"
        },
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "social_media_urls": [],
        "website": "https://layne.name",
        "best_time_to_call": "After 5pm",
        "current_employer": "Sawayn - Hyatt",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": false,
        "key_skills": "Programming, management, fishing",
        "notes": "Aliquid maiores dolores fugit sunt aut est.",
        "source": "Google",
        "is_hot": false,
        "is_active": false,
        "is_registered": false,
        "contact_id": 7241,
        "owner_id": 2658,
        "entered_by_id": 5798,
        "date_created": "2022-07-26T22:15:21.356Z",
        "date_modified": "2022-04-04T13:35:02.823Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{candidate_id}/phones{?page,per_page}

List candidate phones

Parameters
candidate_id

required

string

The candidate to return phones for.

page

required

string

The current page number of phones to return.

per_page

required

string

The number of phones to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/6455/phones \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 869,
  "_links": {...},
  "_embedded": {
    "phones": [
      {
        "id": 9831,
        "number": "461-962-5513",
        "extension": "612",
        "type": "Mobile",
        "date_created": "2022-06-18T02:25:51.369Z",
        "date_modified": "2022-07-19T07:35:21.325Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{candidate_id}/phones/{id}

Get a candidate phone

Parameters
candidate_id

required

string

The candidate to return the phone for.

id

required

string

The ID of the phone to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/9506/phones/9715 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9831,
  "number": "461-962-5513",
  "extension": "612",
  "type": "Mobile",
  "date_created": "2022-06-18T02:25:51.369Z",
  "date_modified": "2022-07-19T07:35:21.325Z",
  "_links": {...},
  "_embedded": {...}
}

POST /candidates/{candidate_id}/phones

Create a candidate phone

Parameters
candidate_id

required

string

The candidate to create the phone for.

Body Parameters
number

required

string

This number MUST begin with the country code. It will not be parsed correctly otherwise.

extension

string

type

required

string

One of mobile, home, work, fax, main, or other.

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/3201/phones \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
Example Response

PUT /candidates/{candidate_id}/phones/{id}

Update a candidate phone

Parameters
candidate_id

required

string

The candidate to update the phone for.

id

required

string

The ID of the phone to update.

Body Parameters
number

required

string

This number MUST begin with the country code. It will not be parsed correctly otherwise.

extension

string

type

required

string

One of mobile, home, work, fax, main, or other.

Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/6271/phones/4224 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
Example Response

DELETE /candidates/{candidate_id}/phones/{id}

Delete a candidate phone

Parameters
candidate_id

required

string

The candidate to delete the phone from.

id

required

string

The ID of the phone to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/6284/phones/3436 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/{candidate_id}/emails{?page,per_page}

List candidate emails

Parameters
candidate_id

required

string

The candidate to return emails for.

page

required

string

The current page number of emails to return.

per_page

required

string

The number of emails to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/4721/emails \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 116,
  "_links": {...},
  "_embedded": {
    "emails": [
      {
        "id": 6426,
        "email": "Joelle_Gutkowski18@yahoo.com",
        "is_primary": true,
        "date_created": "2022-02-05T21:13:48.873Z",
        "date_modified": "2022-12-12T01:21:37.009Z",
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{candidate_id}/emails/{id}

Get a candidate email

Parameters
candidate_id

required

string

The candidate to return the email for.

id

required

string

The ID of the email to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/2987/emails/3951 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6426,
  "email": "Joelle_Gutkowski18@yahoo.com",
  "is_primary": true,
  "date_created": "2022-02-05T21:13:48.873Z",
  "date_modified": "2022-12-12T01:21:37.009Z",
  "_links": {...}
}

POST /candidates/{candidate_id}/emails

Create a candidate email

Parameters
candidate_id

required

string

The candidate to create the email for.

Body Parameters
email

required

string

is_primary

boolean

If a record has any number of emails, exactly one of them must be marked as primary.

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/4217/emails \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Newell.Bins71@gmail.com","is_primary":true}'
Example Response

PUT /candidates/{candidate_id}/emails/{id}

Update a candidate email

Parameters
candidate_id

required

string

The candidate to update the email for.

id

required

string

The ID of the email to update.

Body Parameters
email

required

string

is_primary

boolean

If a record has any number of emails, exactly one of them must be marked as primary.

Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/1765/emails/326 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Newell.Bins71@gmail.com","is_primary":true}'
Example Response

DELETE /candidates/{candidate_id}/emails/{id}

Delete a candidate email

Parameters
candidate_id

required

string

The candidate to delete the email from.

id

required

string

The ID of the email to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/1464/emails/5140 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/custom_fields{?page,per_page}

List candidate custom fields

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.

Parameters
page

required

string

The current page number of custom field definitions to return.

per_page

required

string

The number of custom field definitions to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 482,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7651,
        "data_item_type": "candidate",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /candidates/custom_fields/{id}

Get a candidate custom field

Returned field type will always be one of text, textarea, checkbox, date, dropdown, radio, checkboxes, user, or number.

Parameters
id

required

string

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/custom_fields/7651 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7651,
  "data_item_type": "candidate",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /candidates/{id}/custom_fields{?page,per_page}

List candidate custom field values

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.

Parameters
id

required

string

The ID of the candidate to return custom fields for.

page

required

string

The current page number of custom fields to return.

per_page

required

string

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/6153/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "531",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4117,
        "value": "susanna",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{candidate_id}/custom_fields/{custom_field_id}

Get a candidate custom field value

Get a single custom field value for a candidate.

Parameters
candidate_id

required

string

The ID of the candidate that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/6826/custom_fields/9071 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4117,
  "value": "susanna",
  "_links": {...},
  "_embedded": {...}
}

PUT /candidates/{candidate_id}/custom_fields/{custom_field_id}

Update a candidate custom field

Parameters
candidate_id

required

string

The ID of the candidate that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to update.

Body Parameters
value

required

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/2387/custom_fields/3756 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"freddie"}'
Example Response

GET /candidates/{id}/activities{?page,per_page}

List candidate activities

List all activities associated with a candidate.

Parameters
id

required

string

The ID of the candidate to return activities for.

page

required

string

The current page number of activities to return.

per_page

required

string

The number of activities to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/6496/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 863,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 5126,
        "data_item": {
          "id": 7725,
          "type": "candidate"
        },
        "date_created": "2022-10-11T20:12:09.038Z",
        "regarding_id": 7130,
        "type": "other",
        "notes": "Added candidate to pipeline.",
        "annotation": "General",
        "entered_by_id": 9875,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/{id}/activities

Create a candidate activity

Log an activity against a candidate.

Parameters
id

required

string

The ID of the candidate to create an activity for.

Body Parameters
type

required

string

One of the following activity types: email, meeting, call_talked, call_lvm, call_missed, text_message or other.

regarding_id

number

The ID of the job order that this activity is regarding. Leave null for a general activity.

notes

string

date

string

The datetime the activity took place. If not specified it defaults to the current date and time.

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/3134/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":3172,"notes":"Sequi velit mollitia aut magni iure.","date":"2022-05-18T10:53:54.025Z"}'
Example Response

GET /candidates/{id}/attachments{?page,per_page}

List a candidate attachments

Parameters
id

required

string

The ID of the candidate to return attachments for.

page

required

string

The current page number of attachments to return.

per_page

required

string

The number of attachments to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/7721/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 738,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 267,
        "filename": "readme.txt",
        "is_resume": false,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5007,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

POST /candidates/{id}/attachments{?filename}

Upload a candidate attachment

Parameters
id

required

string

The ID of the candidate that the attachment is being attached to.

filename

required

string

The name to save the file being uploaded as.

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/7683/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

POST /candidates/{id}/resumes{?filename}

Upload a resume

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.

Parameters
id

required

string

The ID of the candidate that the resume is being attached to.

filename

required

string

The name to save the file being uploaded as.

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/469/resumes \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /candidates/{id}/work_history{?page,per_page}

List candidate work history

Parameters
id

required

string

The ID of the candidate to fetch work history for.

page

required

string

The current page number of work history to return.

per_page

required

string

The number of work history items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/5614/work_history \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 921,
  "_links": {...},
  "_embedded": {
    "work_history": [
      {
        "id": 4552,
        "title": "Lead Operations Assistant",
        "candidate_id": 2298,
        "employer": {
          "linked": false,
          "name": "Bernier, Frami and Harvey",
          "location": {
            "city": "East Franciscochester",
            "state": "LA"
          }
        },
        "supervisor": {
          "linked": false,
          "name": "Kara",
          "phone": "(836) 853-3611"
        },
        "is_verified": true,
        "is_current": false,
        "start_date": "2022-12-04T13:56:07.416Z",
        "end_date": "2022-01-08T01:27:07.026Z",
        "reason_for_leaving": "Dolorum velit cupiditate ad voluptatem."
      },
      {...}
    ]
  }
}

GET /candidates/work_history/{id}

Get a candidate work history item

Parameters
id

required

string

The ID of the work history to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/work_history/6176 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4552,
  "title": "Lead Operations Assistant",
  "candidate_id": 2298,
  "employer": {
    "linked": false,
    "name": "Bernier, Frami and Harvey",
    "location": {
      "city": "East Franciscochester",
      "state": "LA"
    }
  },
  "supervisor": {
    "linked": false,
    "name": "Kara",
    "phone": "(836) 853-3611"
  },
  "is_verified": true,
  "is_current": false,
  "start_date": "2022-12-04T13:56:07.416Z",
  "end_date": "2022-01-08T01:27:07.026Z",
  "reason_for_leaving": "Dolorum velit cupiditate ad voluptatem."
}

POST /candidates/{id}/work_history

Create a candidate work history item

Parameters
id

required

string

The ID of the candidate to create work history for.

Body Parameters
title

required

string

employer

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.

supervisor

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
}
is_verified

boolean

is_current

string

If this is set to true, both end_date and reason_for_leaving will be ignored.

start_date

string

end_date

string

reason_for_leaving

string

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/5772/work_history \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Chief Markets Technician","employer":{"linked":false,"name":"Altenwerth - Kertzmann","location":{"city":"Schneiderchester","state":"MI"}},"supervisor":{"linked":false,"name":"Andrew","phone":"(509) 639-9671"},"is_verified":true,"is_current":"false","start_date":"2022-07-02T08:16:37.933Z","end_date":"2022-08-13T18:22:46.655Z","reason_for_leaving":"Eum ut ut dolorem aut et eveniet rerum."}'
Example Response

PUT /candidates/work_history/{id}

Update a candidate work history item

Parameters
id

required

string

The ID of the work history to update.

Body Parameters
title

required

string

employer

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.

supervisor

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
}
is_verified

boolean

is_current

string

If this is set to true, both end_date and reason_for_leaving will be ignored.

start_date

string

end_date

string

reason_for_leaving

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/work_history/6348 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Chief Markets Technician","employer":{"linked":false,"name":"Altenwerth - Kertzmann","location":{"city":"Schneiderchester","state":"MI"}},"supervisor":{"linked":false,"name":"Andrew","phone":"(509) 639-9671"},"is_verified":true,"is_current":"false","start_date":"2022-07-02T08:16:37.933Z","end_date":"2022-08-13T18:22:46.655Z","reason_for_leaving":"Eum ut ut dolorem aut et eveniet rerum."}'
Example Response

DELETE /candidates/work_history/{id}

Delete a candidate work history item

Parameters
id

required

string

The ID of the work history to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/work_history/5409 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/lists{?page,per_page}

List all candidate lists

Parameters
page

required

string

The current page number of lists to return.

per_page

required

string

The number of lists to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 994,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 7246,
        "name": "molestiae",
        "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
        "date_created": "2022-10-30T08:24:37.110Z",
        "date_modified": "2022-12-12T00:57:58.048Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/lists/{id}

Get a candidate list

Parameters
id

required

string

The ID of the candidate list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists/7708 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7246,
  "name": "molestiae",
  "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
  "date_created": "2022-10-30T08:24:37.110Z",
  "date_modified": "2022-12-12T00:57:58.048Z",
  "_links": {...},
  "_embedded": {...}
}

POST /candidates/lists

Create a candidate list

Body Parameters
name

required

string

notes

string

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"expedita","notes":"Non atque facere cumque recusandae aut dolorem quia totam quae."}'
Example Response

DELETE /candidates/lists/{id}

Delete a candidate list

Parameters
id

required

string

The ID of the candidate list to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/lists/2889 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/lists/{id}/items{?page,per_page}

List all candidate list items

Parameters
id

required

string

The ID of the candidate list to return items for.

page

required

string

The current page number of list items to return.

per_page

required

string

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists/1928/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 906,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 7249,
        "date_created": "2022-09-17T02:40:54.697Z",
        "candidate_id": 1208,
        "_links": {...},
        "_embedded": {
          "candidate": {
            "id": 4552,
            "first_name": "Fay",
            "middle_name": "Barton",
            "last_name": "Kunze",
            "title": "Customer Marketing Specialist",
            "emails": {
              "primary": "Ezra_Tremblay88@yahoo.com",
              "secondary": "Ozella_Hamill25@yahoo.com"
            },
            "address": {
              "street": "22840 Maxine Alley",
              "city": "New Jarvis",
              "state": "AL",
              "postal_code": "09774"
            },
            "country_code": "US",
            "social_media_urls": [],
            "website": "https://layne.name",
            "best_time_to_call": "After 5pm",
            "current_employer": "Sawayn - Hyatt",
            "date_available": "Next month",
            "current_pay": "50k",
            "desired_pay": "120k",
            "is_willing_to_relocate": false,
            "key_skills": "Programming, management, fishing",
            "notes": "Aliquid maiores dolores fugit sunt aut est.",
            "source": "Google",
            "is_hot": false,
            "is_active": false,
            "is_registered": false,
            "contact_id": 7241,
            "owner_id": 2658,
            "entered_by_id": 5798,
            "date_created": "2022-07-26T22:15:21.356Z",
            "date_modified": "2022-04-04T13:35:02.823Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

GET /candidates/lists/{list_id}/items/{item_id}

Get a candidate list item

Parameters
list_id

required

string

The ID of the candidate list the item belongs to.

item_id

required

string

The ID of the candidate list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists/3243/items/9933 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7249,
  "date_created": "2022-09-17T02:40:54.697Z",
  "candidate_id": 1208,
  "_links": {...},
  "_embedded": {
    "candidate": {
      "id": 4552,
      "first_name": "Fay",
      "middle_name": "Barton",
      "last_name": "Kunze",
      "title": "Customer Marketing Specialist",
      "emails": {
        "primary": "Ezra_Tremblay88@yahoo.com",
        "secondary": "Ozella_Hamill25@yahoo.com"
      },
      "address": {
        "street": "22840 Maxine Alley",
        "city": "New Jarvis",
        "state": "AL",
        "postal_code": "09774"
      },
      "country_code": "US",
      "social_media_urls": [],
      "website": "https://layne.name",
      "best_time_to_call": "After 5pm",
      "current_employer": "Sawayn - Hyatt",
      "date_available": "Next month",
      "current_pay": "50k",
      "desired_pay": "120k",
      "is_willing_to_relocate": false,
      "key_skills": "Programming, management, fishing",
      "notes": "Aliquid maiores dolores fugit sunt aut est.",
      "source": "Google",
      "is_hot": false,
      "is_active": false,
      "is_registered": false,
      "contact_id": 7241,
      "owner_id": 2658,
      "entered_by_id": 5798,
      "date_created": "2022-07-26T22:15:21.356Z",
      "date_modified": "2022-04-04T13:35:02.823Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /candidates/lists/{id}/items

Create candidate list items

Creating candidate list items attaches the specified candidates to a list.

Parameters
id

required

string

The ID of the candidate list.

Body Parameters
items

array

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/lists/3272/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"candidate_id":3109}]}'
Example Response

DELETE /candidates/lists/{list_id}/items/{item_id}

Delete a candidate list item

Deleting a candidate list item removes a candidate from a list.

Parameters
list_id

required

string

The ID of the candidate list.

item_id

required

string

The ID of the list item to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/lists/2789/items/3434 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/{candidate_id}/applications{?page,per_page}

List applications by candidate

Parameters
candidate_id

required

string

The ID of the candidate to return applications for.

page

required

string

The current page number of list items to return.

per_page

required

string

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/9373/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 312,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 9976,
        "job_id": "506",
        "date_created": "2022-08-16T23:04:56.547Z",
        "_links": {...},
        "_embedded": {
          "fields": []
        }
      },
      {...}
    ]
  }
}

GET /candidates/applications/{application_id}{?page,per_page}

Get a candidate application

Parameters
application_id

required

string

The ID of the applications to return.

page

required

string

The current page number of list items to return.

per_page

required

string

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/applications/7743 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9976,
  "job_id": "506",
  "date_created": "2022-08-16T23:04:56.547Z",
  "_links": {...},
  "_embedded": {
    "fields": []
  }
}

GET /candidates/{candidate_id}/tags{?page,per_page}

List all candidate tags

Parameters
candidate_id

required

string

The ID of the candidate to return tags for.

page

required

string

The current page number of tags to return.

per_page

required

string

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/258/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 927,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 5569,
        "parent_id": 2791,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/{candidate_id}/tags

Replace candidate tags

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.

Parameters
candidate_id

required

string

The ID of the candidate to replace tags on.

Body Parameters
tags

array

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/9125/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

PUT /candidates/{candidate_id}/tags

Attach candidate tags

This will not delete any existing tags on the candidate.

Parameters
candidate_id

required

string

The ID of the candidate to attach tags to.

Body Parameters
tags

array

Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/2565/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

DELETE /candidates/{candidate_id}/tags/{tag_id}

Delete candidate tag

Detaches an individual tag from the candidate.

Parameters
candidate_id

required

string

The ID of the candidate to detach the tag from.

tag_id

required

string

The ID of the tag to detach.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/candidates/5161/tags/1198 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/{id}/thumbnail

Get a candidate thumbnail

Parameters
id

required

string

The ID of the candidate to get the thumbnail of.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/9988/thumbnail \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "source": "attachment",
  "attachment_id": 9440,
  "url": "https://melany.org",
  "_links": {...}
}

PUT /candidates/{id}/thumbnail

Change a candidate thumbnail

Parameters
id

required

string

The ID of the candidate to change the thumbnail of.

Body Parameters
source

required

string

One of attachment, gravatar, or disabled.

attachment_id

number

Only required if source is set to attachment (must be an attachment belonging to the data item)

Example Request
curl -X PUT \
https://api.catsone.com/v3/candidates/5496/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":2282}'
Example Response

Companies

GET /companies{?page,per_page}

List all companies

Parameters
page

required

string

The current page number of companies to return.

per_page

required

string

The number of companies to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 385,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 7669,
        "owner_id": 6648,
        "name": "Barton - Zulauf",
        "website": "http://idell.org",
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "entered_by_id": 7631,
        "social_media_urls": [],
        "notes": "Ratione atque similique quaerat debitis odit natus ut molestiae.",
        "is_hot": false,
        "key_technologies": "",
        "billing_contact_id": 4056,
        "user_groups": [],
        "status_id": 822,
        "date_created": "2022-12-07T19:30:27.021Z",
        "date_modified": "2022-03-24T04:31:54.177Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/{id}

Get a company

Parameters
id

required

string

The ID of the company to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/7669 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7669,
  "owner_id": 6648,
  "name": "Barton - Zulauf",
  "website": "http://idell.org",
  "address": {
    "street": "22840 Maxine Alley",
    "city": "New Jarvis",
    "state": "AL",
    "postal_code": "09774"
  },
  "country_code": "US",
  "entered_by_id": 7631,
  "social_media_urls": [],
  "notes": "Ratione atque similique quaerat debitis odit natus ut molestiae.",
  "is_hot": false,
  "key_technologies": "",
  "billing_contact_id": 4056,
  "user_groups": [],
  "status_id": 822,
  "date_created": "2022-12-07T19:30:27.021Z",
  "date_modified": "2022-03-24T04:31:54.177Z",
  "_links": {...},
  "_embedded": {...}
}

POST /companies{?check_duplicate}

Create a company

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Parameters
check_duplicate

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.

Body Parameters
name

required

string

owner_id

required

number

website

string

phones

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>",
    }
]
address

object

An object containing the address for the company with the following structure:

{
  "street": "<street>",
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

entered_by_id

number

social_media_urls

array

notes

string

is_hot

boolean

key_technologies

string

billing_contact_id

number

custom_fields

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>"
    }
]
user_groups

array

User groups allowed to access this company

Example Request
curl -X POST \
https://api.catsone.com/v3/companies \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Gleason - Lesch","owner_id":5354,"website":"http://evan.info","phones":[{"number":"+16124063451","extension":"664","type":"Main"}],"address":{"street":"3466 Gerhold Lane","city":"Lake Domingoland","state":"North Dakota","postal_code":"72345"},"country_code":"US","entered_by_id":9103,"social_media_urls":[],"notes":"Quaerat recusandae consequatur dicta.","is_hot":false,"key_technologies":"","billing_contact_id":9892,"custom_fields":[{"id":5851,"value":"lorem"}],"user_groups":[]}'
Example Response

PUT /companies/{id}

Update a company

Parameters
id

required

string

The ID of the company to update.

Body Parameters
name

required

string

owner_id

required

number

website

string

phones

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>",
    }
]
address

object

An object containing the address for the company with the following structure:

{
  "street": "<street>",
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

entered_by_id

number

social_media_urls

array

notes

string

is_hot

boolean

key_technologies

string

billing_contact_id

number

custom_fields

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>"
    }
]
user_groups

array

User groups allowed to access this company

Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/307 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Gleason - Lesch","owner_id":5354,"website":"http://evan.info","phones":[{"number":"+16124063451","extension":"664","type":"Main"}],"address":{"street":"3466 Gerhold Lane","city":"Lake Domingoland","state":"North Dakota","postal_code":"72345"},"country_code":"US","entered_by_id":9103,"social_media_urls":[],"notes":"Quaerat recusandae consequatur dicta.","is_hot":false,"key_technologies":"","billing_contact_id":9892,"custom_fields":[{"id":5851,"value":"lorem"}],"user_groups":[]}'
Example Response

DELETE /companies/{id}

Delete a company

Parameters
id

required

string

The ID of the company to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/companies/5437 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{id}/tasks{?page,per_page}

List company tasks

Parameters
id

required

string

The ID of the company to fetch tasks concerning.

page

required

string

The current page number of tasks to return.

per_page

required

string

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/7901/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 290,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 8895,
        "data_item": {
          "id": 3395,
          "type": "company"
        },
        "entered_by_id": 4953,
        "assigned_to_id": 1004,
        "description": "Ad aut quidem in repellendus magnam.",
        "priority": 2,
        "date_due": "2022-02-05T07:31:45.402Z",
        "is_completed": true,
        "date_completed": "2022-01-11T00:30:35.649Z",
        "date_created": "2022-12-04T09:32:32.852Z",
        "date_updated": "2022-01-23T17:13:21.503Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/search{?query,page,per_page}

Search companies

Parameters
query

required

string

The string to search within companies for.

page

required

string

The current page number of companies to return.

per_page

required

string

The number of companies to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/search \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 385,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 7669,
        "owner_id": 6648,
        "name": "Barton - Zulauf",
        "website": "http://idell.org",
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "entered_by_id": 7631,
        "social_media_urls": [],
        "notes": "Ratione atque similique quaerat debitis odit natus ut molestiae.",
        "is_hot": false,
        "key_technologies": "",
        "billing_contact_id": 4056,
        "user_groups": [],
        "status_id": 822,
        "date_created": "2022-12-07T19:30:27.021Z",
        "date_modified": "2022-03-24T04:31:54.177Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /companies/search{?query,page,per_page}

Filter companies

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

Parameters
query

required

string

The optional string to search within companies for.

page

required

string

The current page number of companies to return.

per_page

required

string

The number of companies to return per page.

Body Parameters
field

required

string

The field to filter on. See the above list to determine which fields can be filtered.

filter

required

string

The filter to use. See the above list to determine which fields allow what filters.

value

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.

Example Request
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"}'
Example Response
{
  "count": 25,
  "total": 385,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 7669,
        "owner_id": 6648,
        "name": "Barton - Zulauf",
        "website": "http://idell.org",
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "entered_by_id": 7631,
        "social_media_urls": [],
        "notes": "Ratione atque similique quaerat debitis odit natus ut molestiae.",
        "is_hot": false,
        "key_technologies": "",
        "billing_contact_id": 4056,
        "user_groups": [],
        "status_id": 822,
        "date_created": "2022-12-07T19:30:27.021Z",
        "date_modified": "2022-03-24T04:31:54.177Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/{company_id}/phones{?page,per_page}

List company phones

Parameters
company_id

required

string

The company to return phones for.

page

required

string

The current page number of phones to return.

per_page

required

string

The number of phones to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/5717/phones \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 869,
  "_links": {...},
  "_embedded": {
    "phones": [
      {
        "id": 9831,
        "number": "461-962-5513",
        "extension": "612",
        "type": "Mobile",
        "date_created": "2022-06-18T02:25:51.369Z",
        "date_modified": "2022-07-19T07:35:21.325Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/{company_id}/phones/{id}

Get a company phone

Parameters
company_id

required

string

The company to return the phone for.

id

required

string

The ID of the phone to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/2402/phones/9715 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9831,
  "number": "461-962-5513",
  "extension": "612",
  "type": "Mobile",
  "date_created": "2022-06-18T02:25:51.369Z",
  "date_modified": "2022-07-19T07:35:21.325Z",
  "_links": {...},
  "_embedded": {...}
}

POST /companies/{company_id}/phones

Create a company phone

Parameters
company_id

required

string

The company to create the phone for.

Body Parameters
number

required

string

This number MUST begin with the country code. It will not be parsed correctly otherwise.

extension

string

type

required

string

One of fax, main, or other.

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/9494/phones \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"664","type":"Main"}'
Example Response

PUT /companies/{company_id}/phones/{id}

Update a company phone

Parameters
company_id

required

string

The company to update the phone for.

id

required

string

The ID of the phone to update.

Body Parameters
number

required

string

This number MUST begin with the country code. It will not be parsed correctly otherwise.

extension

string

type

required

string

One of fax, main, or other.

Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/9593/phones/9336 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"664","type":"Main"}'
Example Response

DELETE /companies/{company_id}/phones/{id}

Delete a company phone

Parameters
company_id

required

string

The company to delete the phone from.

id

required

string

The ID of the phone to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/companies/9845/phones/7672 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/custom_fields{?page,per_page}

List company custom fields

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.

Parameters
page

required

string

The current page number of custom field definitions to return.

per_page

required

string

The number of custom field definitions to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 898,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7651,
        "data_item_type": "company",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /companies/custom_fields/{id}

Get a company custom field

Returned field type will always be one of text, textarea, checkbox, date, dropdown, radio, checkboxes, user or number.

Parameters
id

required

string

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/custom_fields/7651 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7651,
  "data_item_type": "company",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /companies/{id}/custom_fields{?page,per_page}

List company custom field values

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.

Parameters
id

required

string

The ID of the company to return custom fields for.

page

required

string

The current page number of custom fields to return.

per_page

required

string

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/8227/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "531",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4117,
        "value": "susanna",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/{company_id}/custom_fields/{custom_field_id}

Get a company custom field value

Get a single custom field value for a company.

Parameters
company_id

required

string

The ID of the company that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/4378/custom_fields/4953 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4117,
  "value": "susanna",
  "_links": {...},
  "_embedded": {...}
}

PUT /companies/{company_id}/custom_fields/{custom_field_id}

Update a company custom field

Parameters
company_id

required

string

The ID of the company that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to update.

Body Parameters
value

required

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/5774/custom_fields/6599 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"freddie"}'
Example Response

GET /companies/statuses{?page,per_page}

List company statuses

Parameters
page

required

string

The current page number of statuses to return.

per_page

required

string

The number of statuses to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/statuses \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 828,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4677,
        "title": "Lead",
        "mapping": "lead",
        "prerequisites": [
          {
            "id": 4451
          }
        ],
        "triggers": [
          {
            "id": 7155
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /companies/statuses/{id}

Get a company status

Parameters
id

required

string

The ID of the status to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/statuses/4677 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4677,
  "title": "Lead",
  "mapping": "lead",
  "prerequisites": [
    {
      "id": 4451
    }
  ],
  "triggers": [
    {
      "id": 7155
    }
  ],
  "_links": {...}
}

POST /companies/{id}/status

Change company status

Parameters
id

required

string

The ID of the company that the status is being attached to.

Body Parameters
status_id

required

number

The ID of the status to attach.

triggers

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>
    }
]
Example Request
curl -X POST \
https://api.catsone.com/v3/companies/1575/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":249,"triggers":[{"id":4590,"fire":false}]}'
Example Response

GET /companies/{id}/attachments{?page,per_page}

List company attachments

Parameters
id

required

string

The ID of the company to return attachments for.

page

required

string

The current page number of attachments to return.

per_page

required

string

The number of attachments to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/9620/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 738,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 267,
        "filename": "readme.txt",
        "is_resume": false,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5007,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

POST /companies/{id}/attachments{?filename}

Upload a company attachment

Parameters
id

required

string

The ID of the company that the attachment is being attached to.

filename

required

string

The name to save the file being uploaded as.

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/1038/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /companies/lists{?page,per_page}

List all company lists

Parameters
page

required

string

The current page number of lists to return.

per_page

required

string

The number of lists to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 994,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 7246,
        "name": "molestiae",
        "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
        "date_created": "2022-10-30T08:24:37.110Z",
        "date_modified": "2022-12-12T00:57:58.048Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/lists/{id}

Get a list

Parameters
id

required

string

The ID of the company list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists/5911 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7246,
  "name": "molestiae",
  "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
  "date_created": "2022-10-30T08:24:37.110Z",
  "date_modified": "2022-12-12T00:57:58.048Z",
  "_links": {...},
  "_embedded": {...}
}

POST /companies/lists

Create a company list

Body Parameters
name

required

string

notes

string

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"expedita","notes":"Non atque facere cumque recusandae aut dolorem quia totam quae."}'
Example Response

DELETE /companies/lists/{id}

Delete a company list

Parameters
id

required

string

The ID of the company list to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/companies/lists/2135 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/lists/{id}/items{?page,per_page}

List all company list items

Parameters
id

required

string

The ID of the company list to return items for.

page

required

string

The current page number of list items to return.

per_page

required

string

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists/6950/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 338,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 7046,
        "date_created": "2022-01-25T13:58:09.394Z",
        "company_id": 1141,
        "_links": {...},
        "_embedded": {
          "company": {
            "id": 7669,
            "owner_id": 6648,
            "name": "Barton - Zulauf",
            "website": "http://idell.org",
            "address": {
              "street": "22840 Maxine Alley",
              "city": "New Jarvis",
              "state": "AL",
              "postal_code": "09774"
            },
            "country_code": "US",
            "entered_by_id": 7631,
            "social_media_urls": [],
            "notes": "Ratione atque similique quaerat debitis odit natus ut molestiae.",
            "is_hot": false,
            "key_technologies": "",
            "billing_contact_id": 4056,
            "user_groups": [],
            "status_id": 822,
            "date_created": "2022-12-07T19:30:27.021Z",
            "date_modified": "2022-03-24T04:31:54.177Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

GET /companies/lists/{list_id}/items/{item_id}

Get a company list item

Parameters
list_id

required

string

The ID of the company list the item belongs to.

item_id

required

string

The ID of the company list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists/9695/items/6912 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7046,
  "date_created": "2022-01-25T13:58:09.394Z",
  "company_id": 1141,
  "_links": {...},
  "_embedded": {
    "company": {
      "id": 7669,
      "owner_id": 6648,
      "name": "Barton - Zulauf",
      "website": "http://idell.org",
      "address": {
        "street": "22840 Maxine Alley",
        "city": "New Jarvis",
        "state": "AL",
        "postal_code": "09774"
      },
      "country_code": "US",
      "entered_by_id": 7631,
      "social_media_urls": [],
      "notes": "Ratione atque similique quaerat debitis odit natus ut molestiae.",
      "is_hot": false,
      "key_technologies": "",
      "billing_contact_id": 4056,
      "user_groups": [],
      "status_id": 822,
      "date_created": "2022-12-07T19:30:27.021Z",
      "date_modified": "2022-03-24T04:31:54.177Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /companies/lists/{id}/items

Create company list items

Creating company list items attaches the specified companies to a list.

Parameters
id

required

string

The ID of the company list.

Body Parameters
items

array

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/lists/9829/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"company_id":6100}]}'
Example Response

DELETE /companies/lists/{list_id}/items/{item_id}

Delete a company list item

Deleting a company list item removes a company from a list.

Parameters
list_id

required

string

The ID of the company list.

item_id

required

string

The ID of the list item to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/companies/lists/9858/items/9319 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{company_id}/tags{?page,per_page}

List all company tags

Parameters
company_id

required

string

The ID of the company to return tags for.

page

required

string

The current page number of tags to return.

per_page

required

string

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/7291/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 927,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 5569,
        "parent_id": 2791,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /companies/{company_id}/tags

Replace company tags

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.

Parameters
company_id

required

string

The ID of the company to replace tags on.

Body Parameters
tags

array

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/5057/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

PUT /companies/{company_id}/tags

Attach company tags

This will not delete any existing tags on the company.

Parameters
company_id

required

string

The ID of the company to attach tags to.

Body Parameters
tags

array

Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/4197/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

DELETE /companies/{company_id}/tags/{tag_id}

Delete company tag

Detaches an individual tag from the company.

Parameters
company_id

required

string

The ID of the company to detach the tag from.

tag_id

required

string

The ID of the tag to detach.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/companies/5737/tags/8472 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{company_id}/departments{?page,per_page}

List all departments

Parameters
company_id

required

string

The ID of the company to return departments for.

page

required

string

The current page number of departments to return.

per_page

required

string

The number of departments to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/8361/departments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 524,
  "_links": {...},
  "_embedded": {
    "departments": [
      {
        "id": 1656,
        "name": "Casper Group",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/departments/{id}

Get a department

Parameters
id

required

string

The ID of the department to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/departments/1656 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 1656,
  "name": "Casper Group",
  "_links": {...},
  "_embedded": {...}
}

POST /companies/{company_id}/departments

Add department

Parameters
company_id

required

string

The ID of the company to add department on.

Body Parameters
name

required

string

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/2990/departments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Marks LLC"}'
Example Response

PUT /companies/departments/{department_id}

Update department

Parameters
department_id

required

string

The ID of the department to update.

Body Parameters
name

required

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/departments/9846 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Marks LLC"}'
Example Response

DELETE /companies/departments/{department_id}

Delete department

Parameters
department_id

required

string

The ID of the department to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/companies/departments/2360 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{id}/thumbnail

Get a company thumbnail

Parameters
id

required

string

The ID of the company to get the thumbnail of.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/2086/thumbnail \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "source": "attachment",
  "attachment_id": 9440,
  "url": "https://melany.org",
  "_links": {...}
}

PUT /companies/{id}/thumbnail

Change a company thumbnail

Parameters
id

required

string

The ID of the company to change the thumbnail of.

Body Parameters
source

required

string

One of attachment, clearbit, or disabled.

attachment_id

number

Only required if source is set to attachment (must be an attachment belonging to the data item)## Trigger (object)

id

number

description

string

is_required

boolean

is_default

boolean

_links

object

Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/2703/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":5856,"id":3190,"description":"Send Candidate Status Change Notification","is_required":false,"is_default":true,"_links":{}}'
Example Response

Contacts

GET /contacts{?page,per_page}

List all contacts

Parameters
page

required

string

The current page number of contacts to return.

per_page

required

string

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 932,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 6111,
        "first_name": "Susanna",
        "last_name": "McKenzie",
        "title": "Regional Infrastructure Agent",
        "reports_to_id": 700,
        "emails": {
          "primary": "Thad.Kuhn@gmail.com",
          "secondary": "Noe_Beatty11@gmail.com"
        },
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "social_media_urls": [],
        "is_hot": false,
        "notes": "Voluptatem deleniti dicta perferendis pariatur repellendus eum maxime in ipsa.",
        "entered_by_id": 4487,
        "status_id": 715,
        "date_created": "2022-05-23T03:58:08.607Z",
        "date_modified": "2022-10-20T02:00:54.841Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/{id}

Get a contact

Parameters
id

required

string

The ID of the contact to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/6111 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6111,
  "first_name": "Susanna",
  "last_name": "McKenzie",
  "title": "Regional Infrastructure Agent",
  "reports_to_id": 700,
  "emails": {
    "primary": "Thad.Kuhn@gmail.com",
    "secondary": "Noe_Beatty11@gmail.com"
  },
  "address": {
    "street": "22840 Maxine Alley",
    "city": "New Jarvis",
    "state": "AL",
    "postal_code": "09774"
  },
  "country_code": "US",
  "social_media_urls": [],
  "is_hot": false,
  "notes": "Voluptatem deleniti dicta perferendis pariatur repellendus eum maxime in ipsa.",
  "entered_by_id": 4487,
  "status_id": 715,
  "date_created": "2022-05-23T03:58:08.607Z",
  "date_modified": "2022-10-20T02:00:54.841Z",
  "_links": {...},
  "_embedded": {...}
}

POST /contacts{?check_duplicate}

Create a contact

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Parameters
check_duplicate

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.

Body Parameters
first_name

required

string

last_name

required

string

owner_id

required

number

The ID of the user that owns this contact record.

company_id

required

number

The ID of the company this contact belongs to.

title

string

The contact's job title.

reports_to_id

number

The ID of the contact that this contact reports to.

has_left_company

boolean

emails

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?>"
    }
]
phones

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>",
    }
]
address

object

An object containing the address for the contact with the following structure:

{
  "street": "<street>",
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

social_media_urls

array

is_hot

boolean

notes

string

custom_fields

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>"
    }
]
Example Request
curl -X POST \
https://api.catsone.com/v3/contacts \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Mariela","last_name":"Hartmann","owner_id":3964,"company_id":6729,"title":"Human Usability Producer","reports_to_id":9329,"has_left_company":false,"emails":[{"email":"Newell.Bins71@gmail.com","is_primary":true}],"phones":[{"number":"+16124063451","extension":"8371","type":"Mobile"}],"address":{"street":"020 Davonte Highway","city":"Daughertyfurt","state":"Idaho","postal_code":"38033"},"country_code":"US","social_media_urls":[],"is_hot":true,"notes":"Voluptatem tenetur distinctio accusamus consectetur.","custom_fields":[{"id":5851,"value":"lorem"}]}'
Example Response

PUT /contacts/{id}

Update a contact

Parameters
id

required

string

The ID of the contact to update.

Body Parameters
first_name

required

string

last_name

required

string

owner_id

required

number

The ID of the user that owns this contact record.

company_id

required

number

The ID of the company this contact belongs to.

title

string

The contact's job title.

reports_to_id

number

The ID of the contact that this contact reports to.

has_left_company

boolean

emails

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?>"
    }
]
phones

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>",
    }
]
address

object

An object containing the address for the contact with the following structure:

{
  "street": "<street>",
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

social_media_urls

array

is_hot

boolean

notes

string

custom_fields

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>"
    }
]
Example Request
curl -X PUT \
https://api.catsone.com/v3/contacts/7345 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Mariela","last_name":"Hartmann","owner_id":3964,"company_id":6729,"title":"Human Usability Producer","reports_to_id":9329,"has_left_company":false,"emails":[{"email":"Newell.Bins71@gmail.com","is_primary":true}],"phones":[{"number":"+16124063451","extension":"8371","type":"Mobile"}],"address":{"street":"020 Davonte Highway","city":"Daughertyfurt","state":"Idaho","postal_code":"38033"},"country_code":"US","social_media_urls":[],"is_hot":true,"notes":"Voluptatem tenetur distinctio accusamus consectetur.","custom_fields":[{"id":5851,"value":"lorem"}]}'
Example Response

DELETE /contacts/{id}

Delete a contact

Parameters
id

required

string

The ID of the contact to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/contacts/3824 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{id}/tasks{?page,per_page}

List contact tasks

Parameters
id

required

string

The ID of the contact to fetch tasks concerning.

page

required

string

The current page number of tasks to return.

per_page

required

string

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/7181/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 595,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 8895,
        "data_item": {
          "id": 2073,
          "type": "contact"
        },
        "entered_by_id": 5182,
        "assigned_to_id": 4227,
        "description": "Eaque voluptas qui voluptatem tenetur qui atque neque natus.",
        "priority": 2,
        "date_due": "2022-02-21T21:02:33.749Z",
        "is_completed": true,
        "date_completed": "2022-04-28T20:25:17.610Z",
        "date_created": "2022-04-26T07:55:26.130Z",
        "date_updated": "2022-09-28T17:12:14.825Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/search{?query,page,per_page}

Search contacts

Parameters
query

required

string

The string to search within contacts for.

page

required

string

The current page number of contacts to return.

per_page

required

string

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/search \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 932,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 6111,
        "first_name": "Susanna",
        "last_name": "McKenzie",
        "title": "Regional Infrastructure Agent",
        "reports_to_id": 700,
        "emails": {
          "primary": "Thad.Kuhn@gmail.com",
          "secondary": "Noe_Beatty11@gmail.com"
        },
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "social_media_urls": [],
        "is_hot": false,
        "notes": "Voluptatem deleniti dicta perferendis pariatur repellendus eum maxime in ipsa.",
        "entered_by_id": 4487,
        "status_id": 715,
        "date_created": "2022-05-23T03:58:08.607Z",
        "date_modified": "2022-10-20T02:00:54.841Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/search{?query,page,per_page}

Filter contacts

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

Parameters
query

required

string

The optional string to search within contacts for.

page

required

string

The current page number of contacts to return.

per_page

required

string

The number of contacts to return per page.

Body Parameters
field

required

string

The field to filter on. See the above list to determine which fields can be filtered.

filter

required

string

The filter to use. See the above list to determine which fields allow what filters.

value

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.

Example Request
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"}'
Example Response
{
  "count": 25,
  "total": 932,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 6111,
        "first_name": "Susanna",
        "last_name": "McKenzie",
        "title": "Regional Infrastructure Agent",
        "reports_to_id": 700,
        "emails": {
          "primary": "Thad.Kuhn@gmail.com",
          "secondary": "Noe_Beatty11@gmail.com"
        },
        "address": {
          "street": "22840 Maxine Alley",
          "city": "New Jarvis",
          "state": "AL",
          "postal_code": "09774"
        },
        "country_code": "US",
        "social_media_urls": [],
        "is_hot": false,
        "notes": "Voluptatem deleniti dicta perferendis pariatur repellendus eum maxime in ipsa.",
        "entered_by_id": 4487,
        "status_id": 715,
        "date_created": "2022-05-23T03:58:08.607Z",
        "date_modified": "2022-10-20T02:00:54.841Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/{contact_id}/phones{?page,per_page}

Lis contact phones

Parameters
contact_id

required

string

The contact to return phones for.

page

required

string

The current page number of phones to return.

per_page

required

string

The number of phones to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/1240/phones \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 869,
  "_links": {...},
  "_embedded": {
    "phones": [
      {
        "id": 9831,
        "number": "461-962-5513",
        "extension": "612",
        "type": "Mobile",
        "date_created": "2022-06-18T02:25:51.369Z",
        "date_modified": "2022-07-19T07:35:21.325Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/{contact_id}/phones/{id}

Get a contact phone

Parameters
contact_id

required

string

The contact to return the phone for.

id

required

string

The ID of the phone to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/4634/phones/9715 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9831,
  "number": "461-962-5513",
  "extension": "612",
  "type": "Mobile",
  "date_created": "2022-06-18T02:25:51.369Z",
  "date_modified": "2022-07-19T07:35:21.325Z",
  "_links": {...},
  "_embedded": {...}
}

POST /contacts/{contact_id}/phones

Create a contact phone

Parameters
contact_id

required

string

The contact to create the phone for.

Body Parameters
number

required

string

This number MUST begin with the country code. It will not be parsed correctly otherwise.

extension

string

type

required

string

One of mobile, home, work, fax, main, or other.

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/1317/phones \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
Example Response

PUT /contacts/{contact_id}/phones/{id}

Update a contact phone

Parameters
contact_id

required

string

The contact to update the phone for.

id

required

string

The ID of the phone to update.

Body Parameters
number

required

string

This number MUST begin with the country code. It will not be parsed correctly otherwise.

extension

string

type

required

string

One of mobile, home, work, fax, main, or other.

Example Request
curl -X PUT \
https://api.catsone.com/v3/contacts/8297/phones/294 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"number":"+16124063451","extension":"8371","type":"Mobile"}'
Example Response

DELETE /contacts/{contact_id}/phones/{id}

Delete a contact phone

Parameters
contact_id

required

string

The contact to delete the phone from.

id

required

string

The ID of the phone to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/contacts/4991/phones/5708 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{contact_id}/emails{?page,per_page}

List contact emails

Parameters
contact_id

required

string

The contact to return emails for.

page

required

string

The current page number of emails to return.

per_page

required

string

The number of emails to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/7851/emails \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 116,
  "_links": {...},
  "_embedded": {
    "emails": [
      {
        "id": 6426,
        "email": "Joelle_Gutkowski18@yahoo.com",
        "is_primary": true,
        "date_created": "2022-02-05T21:13:48.873Z",
        "date_modified": "2022-12-12T01:21:37.009Z",
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /contacts/{contact_id}/emails/{id}

Get a contact email

Parameters
contact_id

required

string

The contact to return the email for.

id

required

string

The ID of the email to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/699/emails/3951 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6426,
  "email": "Joelle_Gutkowski18@yahoo.com",
  "is_primary": true,
  "date_created": "2022-02-05T21:13:48.873Z",
  "date_modified": "2022-12-12T01:21:37.009Z",
  "_links": {...}
}

POST /contacts/{contact_id}/emails

Create a contact email

Parameters
contact_id

required

string

The contact to create the email for.

Body Parameters
email

required

string

is_primary

boolean

If a record has any number of emails, exactly one of them must be marked as primary.

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/8066/emails \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Newell.Bins71@gmail.com","is_primary":true}'
Example Response

PUT /contacts/{contact_id}/emails/{id}

Update a contact email

Parameters
contact_id

required

string

The contact to update the email for.

id

required

string

The ID of the email to update.

Body Parameters
email

required

string

is_primary

boolean

If a record has any number of emails, exactly one of them must be marked as primary.

Example Request
curl -X PUT \
https://api.catsone.com/v3/contacts/4493/emails/473 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"email":"Newell.Bins71@gmail.com","is_primary":true}'
Example Response

DELETE /contacts/{contact_id}/emails/{id}

Delete a contact email

Parameters
contact_id

required

string

The contact to delete the email from.

id

required

string

The ID of the email to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/contacts/1975/emails/5754 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/custom_fields{?page,per_page}

List contact custom fields

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.

Parameters
page

required

string

The current page number of custom field definitions to return.

per_page

required

string

The number of custom field definitions to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 194,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7651,
        "data_item_type": "contact",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /contacts/custom_fields/{id}

Get a contact custom field

Returned field type will always be one of text, textarea, checkbox, date, dropdown, radio, checkboxes, user or number.

Parameters
id

required

string

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/custom_fields/7651 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7651,
  "data_item_type": "contact",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /contacts/{id}/custom_fields{?page,per_page}

List contact custom field values

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.

Parameters
id

required

string

The ID of the contact to return custom fields for.

page

required

string

The current page number of custom fields to return.

per_page

required

string

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/7374/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "531",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4117,
        "value": "susanna",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/{contact_id}/custom_fields/{custom_field_id}

Get a contact custom field value

Get a single custom field value for a contact.

Parameters
contact_id

required

string

The ID of the contact that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/4631/custom_fields/7196 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4117,
  "value": "susanna",
  "_links": {...},
  "_embedded": {...}
}

PUT /contacts/{contact_id}/custom_fields/{custom_field_id}

Update a contact custom field

Parameters
contact_id

required

string

The ID of the contact that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to update.

Body Parameters
value

required

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/contacts/2556/custom_fields/5070 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"freddie"}'
Example Response

GET /contacts/{id}/activities{?page,per_page}

List contact activities

List all activities associated with a contact.

Parameters
id

required

string

The ID of the contact to return activities for.

page

required

string

The current page number of activities to return.

per_page

required

string

The number of activities to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/7775/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 251,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9886,
        "data_item": {
          "id": 2073,
          "type": "contact"
        },
        "date_created": "2022-02-07T19:35:48.967Z",
        "regarding_id": 2432,
        "type": "type_other",
        "notes": "Added candidate to pipeline.",
        "annotation": "General",
        "entered_by_id": 9458,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/{id}/activities

Create a contact activity

Log an activity against a contact.

Parameters
id

required

string

The ID of the contact to create an activity for.

Body Parameters
type

required

string

One of the following activity types: email, meeting, call_talked, call_lvm, call_missed, text_message or other.

regarding_id

number

The ID of the job order that this activity is regarding. Leave null for a general activity.

notes

string

date

string

The datetime the activity took place. If not specified it defaults to the current date and time.

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/1353/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":3172,"notes":"Sequi velit mollitia aut magni iure.","date":"2022-05-18T10:53:54.025Z"}'
Example Response

GET /contacts/statuses{?page,per_page}

List contact statuses

Parameters
page

required

string

The current page number of statuses to return.

per_page

required

string

The number of statuses to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/statuses \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 406,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4677,
        "title": "Employee",
        "mapping": "human_resources",
        "prerequisites": [
          {
            "id": 4451
          }
        ],
        "triggers": [
          {
            "id": 7155
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /contacts/statuses/{id}

Get contact status

Parameters
id

required

string

The ID of the status to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/statuses/4677 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4677,
  "title": "Employee",
  "mapping": "human_resources",
  "prerequisites": [
    {
      "id": 4451
    }
  ],
  "triggers": [
    {
      "id": 7155
    }
  ],
  "_links": {...}
}

POST /contacts/{id}/status{?create_activity}

Change contact status

Parameters
id

required

string

The ID of the contact that the status is being attached to.

create_activity

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.

Body Parameters
status_id

required

number

The ID of the status to attach.

triggers

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>
    }
]
Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/9945/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":249,"triggers":[{"id":4590,"fire":false}]}'
Example Response

GET /contacts/{id}/attachments{?page,per_page}

List contact attachments

Parameters
id

required

string

The ID of the contact to return attachments for.

page

required

string

The current page number of attachments to return.

per_page

required

string

The number of attachments to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/5846/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 738,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 267,
        "filename": "readme.txt",
        "is_resume": false,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5007,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

POST /contacts/{id}/attachments{?filename}

Upload a contact attachment

Parameters
id

required

string

The ID of the contact that the attachment is being attached to.

filename

required

string

The name to save the file being uploaded as.

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/6093/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /contacts/lists{?page,per_page}

List all contact lists

Parameters
page

required

string

The current page number of lists to return.

per_page

required

string

The number of lists to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 994,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 7246,
        "name": "molestiae",
        "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
        "date_created": "2022-10-30T08:24:37.110Z",
        "date_modified": "2022-12-12T00:57:58.048Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/lists/{id}

Get a contact list

Parameters
id

required

string

The ID of the contact list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists/990 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7246,
  "name": "molestiae",
  "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
  "date_created": "2022-10-30T08:24:37.110Z",
  "date_modified": "2022-12-12T00:57:58.048Z",
  "_links": {...},
  "_embedded": {...}
}

POST /contacts/lists

Create a contact list

Body Parameters
name

required

string

notes

string

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"expedita","notes":"Non atque facere cumque recusandae aut dolorem quia totam quae."}'
Example Response

DELETE /contacts/lists/{id}

Delete a contact list

Parameters
id

required

string

The ID of the contact list to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/contacts/lists/2971 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/lists/{id}/items{?page,per_page}

List all contact list items

Parameters
id

required

string

The ID of the contact list to return items for.

page

required

string

The current page number of list items to return.

per_page

required

string

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists/1156/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 527,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 5583,
        "date_created": "2022-09-14T15:19:16.632Z",
        "contact_id": 443,
        "_links": {...},
        "_embedded": {
          "contact": {
            "id": 6111,
            "first_name": "Susanna",
            "last_name": "McKenzie",
            "title": "Regional Infrastructure Agent",
            "reports_to_id": 700,
            "emails": {
              "primary": "Thad.Kuhn@gmail.com",
              "secondary": "Noe_Beatty11@gmail.com"
            },
            "address": {
              "street": "22840 Maxine Alley",
              "city": "New Jarvis",
              "state": "AL",
              "postal_code": "09774"
            },
            "country_code": "US",
            "social_media_urls": [],
            "is_hot": false,
            "notes": "Voluptatem deleniti dicta perferendis pariatur repellendus eum maxime in ipsa.",
            "entered_by_id": 4487,
            "status_id": 715,
            "date_created": "2022-05-23T03:58:08.607Z",
            "date_modified": "2022-10-20T02:00:54.841Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

GET /contacts/lists/{list_id}/items/{item_id}

Get a contact list item

Parameters
list_id

required

string

The ID of the contact list the item belongs to.

item_id

required

string

The ID of the contact list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists/5564/items/4439 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5583,
  "date_created": "2022-09-14T15:19:16.632Z",
  "contact_id": 443,
  "_links": {...},
  "_embedded": {
    "contact": {
      "id": 6111,
      "first_name": "Susanna",
      "last_name": "McKenzie",
      "title": "Regional Infrastructure Agent",
      "reports_to_id": 700,
      "emails": {
        "primary": "Thad.Kuhn@gmail.com",
        "secondary": "Noe_Beatty11@gmail.com"
      },
      "address": {
        "street": "22840 Maxine Alley",
        "city": "New Jarvis",
        "state": "AL",
        "postal_code": "09774"
      },
      "country_code": "US",
      "social_media_urls": [],
      "is_hot": false,
      "notes": "Voluptatem deleniti dicta perferendis pariatur repellendus eum maxime in ipsa.",
      "entered_by_id": 4487,
      "status_id": 715,
      "date_created": "2022-05-23T03:58:08.607Z",
      "date_modified": "2022-10-20T02:00:54.841Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /contacts/lists/{id}/items

Create contact list items

Creating contact list items attaches the specified contacts to a list.

Parameters
id

required

string

The ID of the contact list.

Body Parameters
items

array

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/lists/4268/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"contact_id":2473}]}'
Example Response

DELETE /contacts/lists/{list_id}/items/{item_id}

Delete a contact list item

Deleting a contact list item removes a contact from a list.

Parameters
list_id

required

string

The ID of the contact list.

item_id

required

string

The ID of the list item to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/contacts/lists/1020/items/7141 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{contact_id}/tags{?page,per_page}

List all contact tags

Parameters
contact_id

required

string

The ID of the contact to return tags for.

page

required

string

The current page number of tags to return.

per_page

required

string

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/2648/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 927,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 5569,
        "parent_id": 2791,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/{contact_id}/tags

Replace contact tags

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.

Parameters
contact_id

required

string

The ID of the contact to replace tags on.

Body Parameters
tags

array

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/934/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

PUT /contacts/{contact_id}/tags

Attach contact tags

This will not delete any existing tags on the contact.

Parameters
contact_id

required

string

The ID of the contact to attach tags to.

Body Parameters
tags

array

Example Request
curl -X PUT \
https://api.catsone.com/v3/contacts/900/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

DELETE /contacts/{contact_id}/tags/{tag_id}

Delete contact tag

Detaches an individual tag from the contact.

Parameters
contact_id

required

string

The ID of the contact to detach the tag from.

tag_id

required

string

The ID of the tag to detach.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/contacts/3215/tags/9450 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{id}/thumbnail

Get a contact thumbnail

Parameters
id

required

string

The ID of the contact to get the thumbnail of.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/2653/thumbnail \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "source": "attachment",
  "attachment_id": 9440,
  "url": "https://melany.org",
  "_links": {...}
}

PUT /contacts/{id}/thumbnail

Change a contact thumbnail

Parameters
id

required

string

The ID of the contact to change the thumbnail of.

Body Parameters
source

required

string

One of attachment, gravatar, or disabled.

attachment_id

number

Only required if source is set to attachment (must be an attachment belonging to the data item)

Example Request
curl -X PUT \
https://api.catsone.com/v3/contacts/1021/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":2282}'
Example Response

Events

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.

GET /events{?starting_after_id}

List all events starting after an ID

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.

Parameters
starting_after_id

required

string

Get up to 25 events immediately following (but not including) this id

Example Request
curl -X GET \
https://api.catsone.com/v3/events \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "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": 7725,
          "type": "candidate"
        },
        "user_id": 6725,
        "timestamp": 1510864358
      },
      {...}
    ]
  }
}

GET /events{?starting_after_timestamp}

List all events starting after a timestamp

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.

Parameters
starting_after_timestamp

required

string

Get up to 25 events immediately following (but not including) this timestamp

Example Request
curl -X GET \
https://api.catsone.com/v3/events \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "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": 7725,
          "type": "candidate"
        },
        "user_id": 6725,
        "timestamp": 1510864358
      },
      {...}
    ]
  }
}

Jobs

GET /jobs{?page,per_page}

List all jobs

Parameters
page

required

string

The current page number of jobs to return.

per_page

required

string

The number of jobs to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 269,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6620,
        "title": "Legacy Paradigm Orchestrator",
        "location": {
          "city": "South Edmundborough",
          "state": "MS",
          "postal_code": "05141-3750"
        },
        "country_code": "US",
        "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
        "notes": "Neque facilis et minus.",
        "recruiter_id": 4146,
        "owner_id": 2508,
        "category": null,
        "is_hot": true,
        "start_date": "2022-11-06T23:52:04.874Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5875,
        "department_id": 2899,
        "status_id": 2228,
        "workflow_id": 1413,
        "is_published": false,
        "portal_hidden": true,
        "user_groups": [],
        "date_created": "2022-07-19T14:06:08.954Z",
        "date_modified": "2022-05-31T19:52:31.414Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{id}

Get a job

Parameters
id

required

string

The ID of the job to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/6620 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6620,
  "title": "Legacy Paradigm Orchestrator",
  "location": {
    "city": "South Edmundborough",
    "state": "MS",
    "postal_code": "05141-3750"
  },
  "country_code": "US",
  "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
  "notes": "Neque facilis et minus.",
  "recruiter_id": 4146,
  "owner_id": 2508,
  "category": null,
  "is_hot": true,
  "start_date": "2022-11-06T23:52:04.874Z",
  "salary": null,
  "max_rate": null,
  "duration": "",
  "external_id": null,
  "company_id": 5875,
  "department_id": 2899,
  "status_id": 2228,
  "workflow_id": 1413,
  "is_published": false,
  "portal_hidden": true,
  "user_groups": [],
  "date_created": "2022-07-19T14:06:08.954Z",
  "date_modified": "2022-05-31T19:52:31.414Z",
  "_links": {...},
  "_embedded": {...}
}

POST /jobs{?check_duplicate}

Create a job

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Parameters
check_duplicate

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.

Body Parameters
title

required

string

location

required

object

An object containing the location information for the job with the following structure:

{
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

company_id

required

number

The ID of the company the job belongs to.

department_id

number

The ID of the department the job belongs to (must be a department linked to the specified company)

recruiter_id

number

The ID of the user who is the recruiter for the job.

owner_id

number

The user id of the record owner

category_name

string

is_hot

boolean

start_date

string

salary

string

max_rate

string

duration

string

type

string

openings

number

external_id

string

description

string

notes

string

contact_id

number

The ID of the contact associated with the job.

workflow_id

number

The ID of the workflow to assign to pipelines attached to this job. If not specified, will use the default.

custom_fields

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>"
    }
]
user_groups

array

User groups allowed to access this job

Example Request
curl -X POST \
https://api.catsone.com/v3/jobs \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Central Response Liason","location":{"city":"New Jaquan","state":"UT","postal_code":"71319-4749"},"country_code":"US","company_id":9573,"department_id":4689,"recruiter_id":8326,"owner_id":2581,"category_name":"","is_hot":false,"start_date":"2022-04-21T06:38:38.612Z","salary":"","max_rate":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":8607,"workflow_id":3086,"custom_fields":[{"id":5851,"value":"lorem"}],"user_groups":[]}'
Example Response

PUT /jobs/{id}

Update a job

Parameters
id

required

string

The ID of the job to update.

Body Parameters
title

required

string

location

required

object

An object containing the location information for the job with the following structure:

{
  "city": "<city>",
  "state": "<state>",
  "postal_code": "<postal code>"
}
country_code

string

company_id

required

number

The ID of the company the job belongs to.

department_id

number

The ID of the department the job belongs to (must be a department linked to the specified company)

recruiter_id

number

The ID of the user who is the recruiter for the job.

owner_id

number

The user id of the record owner

category_name

string

is_hot

boolean

start_date

string

salary

string

max_rate

string

duration

string

type

string

openings

number

external_id

string

description

string

notes

string

contact_id

number

The ID of the contact associated with the job.

custom_fields

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>"
    }
]
user_groups

array

User groups allowed to access this job

Example Request
curl -X PUT \
https://api.catsone.com/v3/jobs/269 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Future Optimization Specialist","location":{"city":"Millerfurt","state":"WY","postal_code":"13993-1431"},"country_code":"US","company_id":3195,"department_id":5656,"recruiter_id":6682,"owner_id":2210,"category_name":"","is_hot":false,"start_date":"2022-08-26T22:19:02.688Z","salary":"","max_rate":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":4053,"custom_fields":[{"id":5851,"value":"lorem"}],"user_groups":[]}'
Example Response

DELETE /jobs/{id}

Delete a job

Parameters
id

required

string

The ID of the job to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/jobs/4237 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /jobs/{id}/pipelines{?page,per_page}

List pipelines by job

List all pipelines associated with a job.

Parameters
id

required

string

The ID of the job to return pipelines for.

page

required

string

The current page number of pipelines to return.

per_page

required

string

The number of pipelines to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/6262/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 275,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 313,
        "candidate_id": 9856,
        "job_id": 9974,
        "rating": 1,
        "workflow_id": 795,
        "status_id": 4781,
        "date_created": "2022-06-05T05:11:16.553Z",
        "date_modified": "2022-11-07T13:52:27.700Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{id}/tasks{?page,per_page}

List job tasks

Parameters
id

required

string

The ID of the job to fetch tasks concerning.

page

required

string

The current page number of tasks to return.

per_page

required

string

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/7961/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 802,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 8895,
        "data_item": {
          "id": 3111,
          "type": "job"
        },
        "entered_by_id": 2147,
        "assigned_to_id": 2488,
        "description": "Vero asperiores deserunt.",
        "priority": 2,
        "date_due": "2022-03-27T15:48:47.238Z",
        "is_completed": true,
        "date_completed": "2022-11-14T22:50:01.384Z",
        "date_created": "2022-11-04T13:01:43.349Z",
        "date_updated": "2022-05-08T08:59:49.940Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/search{?query,page,per_page}

Search jobs

Parameters
query

required

string

The string to search within jobs for.

page

required

string

The current page number of jobs to return.

per_page

required

string

The number of jobs to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/search \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 269,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6620,
        "title": "Legacy Paradigm Orchestrator",
        "location": {
          "city": "South Edmundborough",
          "state": "MS",
          "postal_code": "05141-3750"
        },
        "country_code": "US",
        "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
        "notes": "Neque facilis et minus.",
        "recruiter_id": 4146,
        "owner_id": 2508,
        "category": null,
        "is_hot": true,
        "start_date": "2022-11-06T23:52:04.874Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5875,
        "department_id": 2899,
        "status_id": 2228,
        "workflow_id": 1413,
        "is_published": false,
        "portal_hidden": true,
        "user_groups": [],
        "date_created": "2022-07-19T14:06:08.954Z",
        "date_modified": "2022-05-31T19:52:31.414Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /jobs/search{?query,page,per_page}

Filter jobs

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
`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

Parameters
query

required

string

The optional string to search within jobs for.

page

required

string

The current page number of jobs to return.

per_page

required

string

The number of jobs to return per page.

Body Parameters
field

required

string

The field to filter on. See the above list to determine which fields can be filtered.

filter

required

string

The filter to use. See the above list to determine which fields allow what filters.

value

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.

Example Request
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"}'
Example Response
{
  "count": 25,
  "total": 269,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6620,
        "title": "Legacy Paradigm Orchestrator",
        "location": {
          "city": "South Edmundborough",
          "state": "MS",
          "postal_code": "05141-3750"
        },
        "country_code": "US",
        "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
        "notes": "Neque facilis et minus.",
        "recruiter_id": 4146,
        "owner_id": 2508,
        "category": null,
        "is_hot": true,
        "start_date": "2022-11-06T23:52:04.874Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5875,
        "department_id": 2899,
        "status_id": 2228,
        "workflow_id": 1413,
        "is_published": false,
        "portal_hidden": true,
        "user_groups": [],
        "date_created": "2022-07-19T14:06:08.954Z",
        "date_modified": "2022-05-31T19:52:31.414Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/custom_fields{?page,per_page}

List job custom fields

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.

Parameters
page

required

string

The current page number of custom field definitions to return.

per_page

required

string

The number of custom field definitions to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 477,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7651,
        "data_item_type": "job",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /jobs/custom_fields/{id}

Get a job custom field

Returned field type will always be one of text, textarea, checkbox, date, dropdown, radio, checkboxes, user or number.

Parameters
id

required

string

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/custom_fields/7651 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7651,
  "data_item_type": "job",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /jobs/{id}/custom_fields{?page,per_page}

List job custom field values

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.

Parameters
id

required

string

The ID of the job to return custom fields for.

page

required

string

The current page number of custom fields to return.

per_page

required

string

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/7598/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "531",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4117,
        "value": "susanna",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{job_id}/custom_fields/{custom_field_id}

Get a job custom field value

Get a single custom field value for a job.

Parameters
job_id

required

string

The ID of the job that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/4716/custom_fields/1304 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4117,
  "value": "susanna",
  "_links": {...},
  "_embedded": {...}
}

PUT /jobs/{job_id}/custom_fields/{custom_field_id}

Update a job custom field

Parameters
job_id

required

string

The ID of the job that the custom field belongs to.

custom_field_id

required

string

The ID of the custom field to update.

Body Parameters
value

required

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/jobs/9809/custom_fields/4944 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"freddie"}'
Example Response

GET /jobs/statuses{?page,per_page}

List job statuses

Parameters
page

required

string

The current page number of statuses to return.

per_page

required

string

The number of statuses to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/statuses \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 480,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4677,
        "title": "Active",
        "mapping": 0,
        "prerequisites": [
          {
            "id": 4451
          }
        ],
        "triggers": [
          {
            "id": 7155
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /jobs/statuses/{id}

Get a job status

Parameters
id

required

string

The ID of the status to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/statuses/4677 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4677,
  "title": "Active",
  "mapping": 0,
  "prerequisites": [
    {
      "id": 4451
    }
  ],
  "triggers": [
    {
      "id": 7155
    }
  ],
  "_links": {...}
}

POST /jobs/{id}/status

Change job status

Parameters
id

required

string

The ID of the job that the status is being attached to.

Body Parameters
status_id

required

number

The ID of the status to attach.

triggers

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>
    }
]
Example Request
curl -X POST \
https://api.catsone.com/v3/jobs/2993/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":249,"triggers":[{"id":4590,"fire":false}]}'
Example Response

GET /jobs/{id}/attachments{?page,per_page}

List job attachments

Parameters
id

required

string

The ID of the candidate to return attachments for.

page

required

string

The current page number of attachments to return.

per_page

required

string

The number of attachments to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/5556/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 738,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 267,
        "filename": "readme.txt",
        "is_resume": false,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5007,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

POST /jobs/{id}/attachments{?filename}

Upload a job attachment

Parameters
id

required

string

The ID of the job that the attachment is being attached to.

filename

required

string

The name to save the file being uploaded as.

Example Request
curl -X POST \
https://api.catsone.com/v3/jobs/660/attachments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /jobs/lists{?page,per_page}

List all job lists

Parameters
page

required

string

The current page number of lists to return.

per_page

required

string

The number of lists to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 994,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 7246,
        "name": "molestiae",
        "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
        "date_created": "2022-10-30T08:24:37.110Z",
        "date_modified": "2022-12-12T00:57:58.048Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/lists/{id}

Get a job list

Parameters
id

required

string

The ID of the job list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists/1832 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7246,
  "name": "molestiae",
  "notes": "Qui sit sunt deleniti iusto voluptatem ut ullam.",
  "date_created": "2022-10-30T08:24:37.110Z",
  "date_modified": "2022-12-12T00:57:58.048Z",
  "_links": {...},
  "_embedded": {...}
}

POST /jobs/lists

Create a job list

Body Parameters
name

required

string

notes

string

Example Request
curl -X POST \
https://api.catsone.com/v3/jobs/lists \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"expedita","notes":"Non atque facere cumque recusandae aut dolorem quia totam quae."}'
Example Response

DELETE /jobs/lists/{id}

Delete a job list

Parameters
id

required

string

The ID of the job list to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/jobs/lists/1677 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /jobs/lists/{id}/items{?page,per_page}

List all job list items

Parameters
id

required

string

The ID of the job list to return items for.

page

required

string

The current page number of list items to return.

per_page

required

string

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists/4161/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 335,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 6332,
        "date_created": "2022-01-15T03:20:18.131Z",
        "job_id": 1264,
        "_links": {...},
        "_embedded": {
          "job": {
            "id": 6620,
            "title": "Legacy Paradigm Orchestrator",
            "location": {
              "city": "South Edmundborough",
              "state": "MS",
              "postal_code": "05141-3750"
            },
            "country_code": "US",
            "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
            "notes": "Neque facilis et minus.",
            "recruiter_id": 4146,
            "owner_id": 2508,
            "category": null,
            "is_hot": true,
            "start_date": "2022-11-06T23:52:04.874Z",
            "salary": null,
            "max_rate": null,
            "duration": "",
            "external_id": null,
            "company_id": 5875,
            "department_id": 2899,
            "status_id": 2228,
            "workflow_id": 1413,
            "is_published": false,
            "portal_hidden": true,
            "user_groups": [],
            "date_created": "2022-07-19T14:06:08.954Z",
            "date_modified": "2022-05-31T19:52:31.414Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

GET /jobs/lists/{list_id}/items/{item_id}

Get a job list item

Parameters
list_id

required

string

The ID of the job list the item belongs to.

item_id

required

string

The ID of the job list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists/4977/items/7817 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6332,
  "date_created": "2022-01-15T03:20:18.131Z",
  "job_id": 1264,
  "_links": {...},
  "_embedded": {
    "job": {
      "id": 6620,
      "title": "Legacy Paradigm Orchestrator",
      "location": {
        "city": "South Edmundborough",
        "state": "MS",
        "postal_code": "05141-3750"
      },
      "country_code": "US",
      "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
      "notes": "Neque facilis et minus.",
      "recruiter_id": 4146,
      "owner_id": 2508,
      "category": null,
      "is_hot": true,
      "start_date": "2022-11-06T23:52:04.874Z",
      "salary": null,
      "max_rate": null,
      "duration": "",
      "external_id": null,
      "company_id": 5875,
      "department_id": 2899,
      "status_id": 2228,
      "workflow_id": 1413,
      "is_published": false,
      "portal_hidden": true,
      "user_groups": [],
      "date_created": "2022-07-19T14:06:08.954Z",
      "date_modified": "2022-05-31T19:52:31.414Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /jobs/lists/{id}/items

Create job list items

Creating job list items attaches the specified jobs to a list.

Parameters
id

required

string

The ID of the job list.

Body Parameters
items

array

Example Request
curl -X POST \
https://api.catsone.com/v3/jobs/lists/4212/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"job_id":5611}]}'
Example Response

DELETE /jobs/lists/{list_id}/items/{item_id}

Delete a job list item

Deleting a job list item removes a job from a list.

Parameters
list_id

required

string

The ID of the job list.

item_id

required

string

The ID of the list item to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/jobs/lists/6949/items/1949 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /jobs/{job_id}/applications{?page,per_page}

List applications by job

Parameters
job_id

required

string

The ID of the job to return applications for.

page

required

string

The current page number of contacts to return.

per_page

required

string

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/7221/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 786,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 9976,
        "description": "Alias eligendi velit id expedita.",
        "header": "Nihil aut hic occaecati laborum mollitia sapiente et commodi omnis.",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/applications/{application_id}{?page,per_page}

Get a job application

Parameters
application_id

required

string

The ID of the job application.

page

required

string

The current page number of contacts to return.

per_page

required

string

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/applications/1953 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9976,
  "description": "Alias eligendi velit id expedita.",
  "header": "Nihil aut hic occaecati laborum mollitia sapiente et commodi omnis.",
  "_links": {...},
  "_embedded": {...}
}

GET /jobs/applications/{application_id}/fields{?page,per_page}

List job application fields

Parameters
application_id

required

string

The ID of the job application.

page

required

string

The current page number of contacts to return.

per_page

required

string

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/applications/5259/fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 991,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 7735,
        "title": "Qui facilis quo adipisci debitis doloribus ab incidunt eveniet beatae.",
        "position": 0,
        "type": "text",
        "answers": [],
        "is_required": false,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{job_id}/tags{?page,per_page}

List all job tags

Parameters
job_id

required

string

The ID of the job to return tags for.

page

required

string

The current page number of tags to return.

per_page

required

string

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/7823/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 927,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 5569,
        "parent_id": 2791,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /jobs/{job_id}/tags

Replace job tags

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.

Parameters
job_id

required

string

The ID of the job to replace tags on.

Body Parameters
tags

array

Example Request
curl -X POST \
https://api.catsone.com/v3/jobs/3139/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

PUT /jobs/{job_id}/tags

Attach job tags

This will not delete any existing tags on the candidate.

Parameters
job_id

required

string

The ID of the job to attach tags to.

Body Parameters
tags

array

Example Request
curl -X PUT \
https://api.catsone.com/v3/jobs/9333/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":5425}]}'
Example Response

DELETE /jobs/{job_id}/tags/{tag_id}

Delete job tag

Detaches an individual tag from the job.

Parameters
job_id

required

string

The ID of the job to detach the tag from.

tag_id

required

string

The ID of the tag to detach.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/jobs/5293/tags/7099 \
-H 'authorization: Token <Your API Key>'
Example Response

Pipelines

GET /pipelines{?page,per_page}

List all pipelines

Parameters
page

required

string

The current page number of pipelines to return.

per_page

required

string

The number of pipelines to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 275,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 313,
        "candidate_id": 9856,
        "job_id": 9974,
        "rating": 1,
        "workflow_id": 795,
        "status_id": 4781,
        "date_created": "2022-06-05T05:11:16.553Z",
        "date_modified": "2022-11-07T13:52:27.700Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /pipelines/{id}

Get a pipeline

Parameters
id

required

string

The ID of the pipeline to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/313 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 313,
  "candidate_id": 9856,
  "job_id": 9974,
  "rating": 1,
  "workflow_id": 795,
  "status_id": 4781,
  "date_created": "2022-06-05T05:11:16.553Z",
  "date_modified": "2022-11-07T13:52:27.700Z",
  "_links": {...},
  "_embedded": {...}
}

POST /pipelines{?create_activity}

Create a pipeline

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Parameters
create_activity

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.

Body Parameters
candidate_id

required

number

The ID of the candidate that this pipeline is regarding.

job_id

required

number

The ID of the job order that this pipeline is for.

rating

number

The candidate's rating (0-5) for this job order pipeline.

Example Request
curl -X POST \
https://api.catsone.com/v3/pipelines \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"candidate_id":2516,"job_id":4852,"rating":5}'
Example Response

PUT /pipelines/{id}

Update a pipeline

Parameters
id

required

string

The ID of the pipeline to update.

Body Parameters
rating

number

The candidate's rating (0-5) for this job order pipeline.

Example Request
curl -X PUT \
https://api.catsone.com/v3/pipelines/3350 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"rating":5}'
Example Response

DELETE /pipeline/{id}{?create_activity}

Delete a pipeline

Parameters
create_activity

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.

id

required

string

The ID of the pipeline to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/pipeline/9530 \
-H 'authorization: Token <Your API Key>'
Example Response

POST /pipelines/search{?page,per_page}

Filter Pipelines

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

Parameters
page

required

string

The current page number of pipelines to return.

per_page

required

string

The number of pipelines to return per page.

Body Parameters
field

required

string

The field to filter on. See the above list to determine which fields can be filtered.

filter

required

string

The filter to use. See the above list to determine which fields allow what filters.

value

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.

Example Request
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"}'
Example Response
{
  "count": 25,
  "total": 275,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 313,
        "candidate_id": 9856,
        "job_id": 9974,
        "rating": 1,
        "workflow_id": 795,
        "status_id": 4781,
        "date_created": "2022-06-05T05:11:16.553Z",
        "date_modified": "2022-11-07T13:52:27.700Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /pipelines/workflows{?page,per_page}

List workflows

Parameters
page

required

string

The current page number of workflows to return.

per_page

required

string

The number of workflows to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 10,
  "total": 10,
  "_links": {...},
  "_embedded": {
    "workflows": [
      {
        "id": 6725,
        "title": "Qui neque possimus corrupti ab doloribus error.",
        "is_default": false,
        "date_modified": "2022-08-13T06:22:06.402Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /pipelines/workflows/{id}

Get a workflow

Parameters
id

required

string

The ID of the workflow to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows/4843 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6725,
  "title": "Qui neque possimus corrupti ab doloribus error.",
  "is_default": false,
  "date_modified": "2022-08-13T06:22:06.402Z",
  "_links": {...},
  "_embedded": {...}
}

GET /pipelines/workflow/{workflow_id}/statuses{?page,per_page}

List workflow statuses

Parameters
page

required

string

The current page number of statuses to return.

per_page

required

string

The number of statuses to return per page.

workflow_id

required

string

The ID of the workflow to return statuses for.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/workflow/4843/statuses \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 175,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4677,
        "title": "Offered",
        "mapping": 0,
        "prerequisites": [
          {
            "id": 4451
          }
        ],
        "triggers": [
          {
            "id": 7155
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /pipelines/workflows/{workflow_id}/statuses/{status_id}

Get a workflow status

Parameters
workflow_id

required

string

The ID of the workflow to return statuses for.

status_id

required

string

The ID of the status to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/workflows/4843/statuses/4677 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4677,
  "title": "Offered",
  "mapping": 0,
  "prerequisites": [
    {
      "id": 4451
    }
  ],
  "triggers": [
    {
      "id": 7155
    }
  ],
  "_links": {...}
}

GET /pipelines/{id}/statuses

Get pipeline historical statuses

Parameters
id

required

string

The ID of the pipeline to fetch status history from

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/9874/statuses \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 789,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4677,
        "from_id": 6447,
        "workflow_id": 753,
        "title": "Lead",
        "mapping": "lead",
        "is_current": true,
        "user_id": 6725,
        "date_changed": "2022-08-20T05:01:57.082Z",
        "_links": {...}
      },
      {...}
    ]
  }
}

POST /pipelines/{id}/status{?create_activity}

Change pipeline status

Parameters
id

required

string

The ID of the pipeline that the status is being attached to.

create_activity

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.

Body Parameters
status_id

required

number

The ID of the status to attach.

triggers

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>
    }
]
Example Request
curl -X POST \
https://api.catsone.com/v3/pipelines/3980/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":249,"triggers":[{"id":4590,"fire":false}]}'
Example Response

Portals

GET /portals{?page,per_page}

List all portals

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.

Parameters
page

required

string

The current page number of portals to return.

per_page

required

string

The number of portals to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 221,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 6157,
        "name": "Veniam quod nihil ratione ipsa aut.",
        "date_created": "2022-02-19T22:00:18.364Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /portals/{id}

Get a portal

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.

Parameters
id

required

string

The ID of the portal to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals/6157 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6157,
  "name": "Veniam quod nihil ratione ipsa aut.",
  "date_created": "2022-02-19T22:00:18.364Z",
  "_links": {...},
  "_embedded": {...}
}

GET /portals/{id}/jobs{?page,per_page}

List portal jobs

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.

Parameters
id

required

string

The ID of the portal to return jobs for.

page

required

string

The current page number of jobs to return.

per_page

required

string

The number of jobs to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals/6157/jobs \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 269,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6620,
        "title": "Legacy Paradigm Orchestrator",
        "location": {
          "city": "South Edmundborough",
          "state": "MS",
          "postal_code": "05141-3750"
        },
        "country_code": "US",
        "description": "Voluptates id fugit rerum quis consequuntur impedit. Perferendis voluptatem nemo voluptate illum. Cupiditate dolores aut qui sunt occaecati nihil culpa incidunt sed.",
        "notes": "Neque facilis et minus.",
        "recruiter_id": 4146,
        "owner_id": 2508,
        "category": null,
        "is_hot": true,
        "start_date": "2022-11-06T23:52:04.874Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5875,
        "department_id": 2899,
        "status_id": 2228,
        "workflow_id": 1413,
        "is_published": false,
        "portal_hidden": true,
        "user_groups": [],
        "date_created": "2022-07-19T14:06:08.954Z",
        "date_modified": "2022-05-31T19:52:31.414Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /portals/{portal_id}/jobs/{job_id}

Submit

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.

Parameters
portal_id

required

string

The ID of the portal the job being submitted to is on.

job_id

required

string

The ID of the job the application is being submitted for.

Body Parameters
fields

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"
}
source

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".

Example Request
curl -X POST \
https://api.catsone.com/v3/portals/9096/jobs/129 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"fields":[{"id":2407,"value":"consectetur"}],"source":"Google"}'
Example Response

PUT /portals/{portal_id}/jobs/{job_id}

Publish portal job

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. {}.

Parameters
portal_id

required

string

The ID of the portal the job being submitted to is on.

job_id

required

string

The ID of the job the application is being submitted for.

Body Parameters
Example Request
curl -X PUT \
https://api.catsone.com/v3/portals/3964/jobs/3468 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{}'
Example Response

DELETE /portals/{portal_id}/jobs/{job_id}

Unpublish portal job

This endpoint allows you to remove a job from a portal

Parameters
portal_id

required

string

The ID of the portal the job being submitted to is on.

job_id

required

string

The ID of the job the application is being submitted for.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/portals/1354/jobs/7845 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /portals/{id}/registration

Get portal registration application

Parameters
id

required

string

The ID of the portal to return registration application for.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals/6157/registration \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9976,
  "description": "Alias eligendi velit id expedita.",
  "header": "Nihil aut hic occaecati laborum mollitia sapiente et commodi omnis.",
  "_links": {...},
  "_embedded": {...}
}

POST /portals/{id}/registration

Submit portal registration application

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.

Parameters
id

required

string

The ID of the portal being submitted to.

Body Parameters
fields

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"
}
source

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".

Example Request
curl -X POST \
https://api.catsone.com/v3/portals/6157/registration \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"fields":[{"id":2407,"value":"consectetur"}],"source":"Google"}'
Example Response

Site

Get information the site associated with the API token being used.

GET /site

Get site

Example Request
curl -X GET \
https://api.catsone.com/v3/site \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4155,
  "mode": "recruiter",
  "subdomain": "kitten",
  "_links": {...},
  "_embedded": {...}
}

Statuses

Tags

GET /tags{?page,per_page}

List all tags

Parameters
page

required

string

The current page number of tags to return.

per_page

required

string

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 927,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 5569,
        "parent_id": 2791,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /tags/{id}

Get a tag

Parameters
id

required

string

The ID of the tag to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/tags/5569 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5569,
  "parent_id": 2791,
  "title": "My Cool Tag Name",
  "_links": {...},
  "_embedded": {...}
}

Tasks

GET /tasks{?page,per_page}

List all tasks

Parameters
page

required

string

The current page number of tasks to return.

per_page

required

string

The number of tasks to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 303,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 8895,
        "data_item": {
          "id": 5621,
          "type": "job"
        },
        "entered_by_id": 3255,
        "assigned_to_id": 7357,
        "description": "Asperiores rerum ut velit maxime quasi saepe repudiandae ea.",
        "priority": 2,
        "date_due": "2022-10-24T04:00:57.184Z",
        "is_completed": true,
        "date_completed": "2022-04-24T17:38:41.871Z",
        "date_created": "2022-06-27T17:34:29.646Z",
        "date_updated": "2022-10-22T20:26:12.827Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /tasks/{id}

Get a task

Parameters
id

required

string

The ID of the task to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/tasks/8895 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 8895,
  "data_item": {
    "id": 5621,
    "type": "job"
  },
  "entered_by_id": 3255,
  "assigned_to_id": 7357,
  "description": "Asperiores rerum ut velit maxime quasi saepe repudiandae ea.",
  "priority": 2,
  "date_due": "2022-10-24T04:00:57.184Z",
  "is_completed": true,
  "date_completed": "2022-04-24T17:38:41.871Z",
  "date_created": "2022-06-27T17:34:29.646Z",
  "date_updated": "2022-10-22T20:26:12.827Z",
  "_links": {...},
  "_embedded": {...}
}

POST /tasks

Create a task

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Body Parameters
data_item

DataItem

A DataItem the object is about, or null for a general task

assigned_to_id

number

The user to assign the task to

description

string

priority

number

A number 1-5, with 1 being the lowest priority

date_due

string

If null the task will be assigned ASAP as in the CATS UI

Example Request
curl -X POST \
https://api.catsone.com/v3/tasks \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"data_item":{"id":5621,"type":"job"},"assigned_to_id":8677,"description":"Dolorem aut omnis officia non odio.","priority":3,"date_due":"2022-02-08T23:59:08.982Z"}'
Example Response

PUT /tasks/{id}

Update a task

Parameters
id

required

string

The ID of the task to update.

Body Parameters
assigned_to_id

number

The user to assign the task to

description

string

priority

number

A number 1-5, with 1 being the lowest priority

date_due

string

If null the task will be assigned ASAP as in the CATS UI

is_completed

boolean

Example Request
curl -X PUT \
https://api.catsone.com/v3/tasks/7348 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"assigned_to_id":3189,"description":"Architecto sint dolores.","priority":3,"date_due":"2022-09-23T19:48:36.676Z","is_completed":true}'
Example Response

DELETE /tasks/{id}

Delete a task

Parameters
id

required

string

The ID of the task to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/tasks/3574 \
-H 'authorization: Token <Your API Key>'
Example Response

Triggers

GET /triggers{?page,per_page}

List all triggers

Parameters
page

required

string

The current page number of triggers to return.

per_page

required

string

The number of triggers to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/triggers \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 193,
  "_links": {...},
  "_embedded": {
    "triggers": [
      {
        "id": 3190
      },
      {...}
    ]
  }
}

GET /triggers/{id}

Get a trigger

Parameters
id

required

string

The ID of the trigger to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/triggers/3190 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3190
}

Users

GET /users{?page,per_page}

List all users

Parameters
page

required

string

The current page number of users to return.

per_page

required

string

The number of users to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/users \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 10,
  "total": 10,
  "_links": {...},
  "_embedded": {
    "users": [
      {
        "id": 6725,
        "username": "Judah_Kautzer0@hotmail.com",
        "first_name": "Alvena",
        "last_name": "Crist",
        "title": "Lead Research Representative",
        "access_level: `add_edit_delete`": "",
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /users/{id}

Get a user

Parameters
id

required

string

The ID of the user to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/users/6725 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6725,
  "username": "Judah_Kautzer0@hotmail.com",
  "first_name": "Alvena",
  "last_name": "Crist",
  "title": "Lead Research Representative",
  "access_level: `add_edit_delete`": "",
  "_links": {...}
}

Webhooks

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.

GET /webhooks{?page,per_page}

List all webhooks

Parameters
page

required

string

The current page number of webhooks to return.

per_page

required

string

The number of webhooks to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/webhooks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 723,
  "_links": {...},
  "_embedded": {
    "webhooks": [
      {
        "id": 2245,
        "event": "candidate.created",
        "target_url": "https://mmountain.herokuapp.com/kAa5An56ew"
      },
      {...}
    ]
  }
}

GET /webhooks/{id}

Get a webhook

Parameters
id

required

string

The ID of the webhook to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/webhooks/2245 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2245,
  "event": "candidate.created",
  "target_url": "https://mmountain.herokuapp.com/kAa5An56ew"
}

POST /webhooks

Create a webhook

As with all POST endpoints, a location header will be returned with a url to the newly created resource.

Body Parameters
events

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

target_url

required

string

URL to post the record to once the event is triggered.

secret

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
}
Example Request
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"}'
Example Response

DELETE /webhooks/{id}

Delete a webhook

A webhook will also be deleted if target_url responds with status code 410.

Parameters
id

required

string

The ID of the webhook to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/webhooks/9307 \
-H 'authorization: Token <Your API Key>'
Example Response

Work History

GET /work_history/{work_history_id}

Get a work history

Parameters
work_history_id

required

string

The ID of the work history to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/work_history/6176 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4552,
  "title": "Lead Operations Assistant",
  "candidate_id": 2298,
  "employer": {
    "linked": false,
    "name": "Bernier, Frami and Harvey",
    "location": {
      "city": "East Franciscochester",
      "state": "LA"
    }
  },
  "supervisor": {
    "linked": false,
    "name": "Kara",
    "phone": "(836) 853-3611"
  },
  "is_verified": true,
  "is_current": false,
  "start_date": "2022-12-04T13:56:07.416Z",
  "end_date": "2022-01-08T01:27:07.026Z",
  "reason_for_leaving": "Dolorum velit cupiditate ad voluptatem."
}

PUT /work_history/{work_history_id}

Update a work history

Parameters
work_history_id

required

string

The ID of the work history to update.

Body Parameters
title

required

string

employer

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.

supervisor

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
}
is_verified

boolean

is_current

string

If this is set to true, both end_date and reason_for_leaving will be ignored.

start_date

string

end_date

string

reason_for_leaving

string

Example Request
curl -X PUT \
https://api.catsone.com/v3/work_history/6176 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Chief Markets Technician","employer":{"linked":false,"name":"Altenwerth - Kertzmann","location":{"city":"Schneiderchester","state":"MI"}},"supervisor":{"linked":false,"name":"Andrew","phone":"(509) 639-9671"},"is_verified":true,"is_current":"false","start_date":"2022-07-02T08:16:37.933Z","end_date":"2022-08-13T18:22:46.655Z","reason_for_leaving":"Eum ut ut dolorem aut et eveniet rerum."}'
Example Response

DELETE /work_history/{work_history_id}

Delete a work history

Parameters
work_history_id

required

string

The ID of the work history to delete.

Example Request
curl -X DELETE \
https://api.catsone.com/v3/work_history/5372 \
-H 'authorization: Token <Your API Key>'
Example Response