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 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": 3497,
  "first_name": "Chanel",
  "last_name": "Dare",
  "owner_id": 8989,
  ...
  "_links": {
    "self": {
      "href": "/candidates/3497"
    },
    "custom_fields": {
      "href": "/candidates/3497/custom_fields"
    },
    "owner": {
      "href": "/users/8989"
    },
    "activities": {
      "href": "/candidates/3497/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": "orlando",
      ...
    },
    {...}
  ]
}

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

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

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": 806,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 446,
        "data_item": {
          "id": 5486,
          "type": "candidate"
        },
        "date": "2016-03-07T09:19:32.501Z",
        "regarding_id": 9213,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 5439,
        "date_created": "2016-09-07T05:44:25.366Z",
        "date_modified": "2016-01-08T13:28:02.269Z",
        "_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/446 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 446,
  "data_item": {
    "id": 5486,
    "type": "candidate"
  },
  "date": "2016-03-07T09:19:32.501Z",
  "regarding_id": 9213,
  "type": "call_lvm",
  "notes": "Left voicemail.",
  "annotation": "General",
  "entered_by_id": 5439,
  "date_created": "2016-09-07T05:44:25.366Z",
  "date_modified": "2016-01-08T13:28:02.269Z",
  "_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, 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/8246 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":4927,"notes":"Provident ut voluptate.","date":"2016-10-28T16:01:29.333Z"}'
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={query}

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?query=Otto' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 806,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 446,
        "data_item": {
          "id": 5486,
          "type": "candidate"
        },
        "date": "2016-03-07T09:19:32.501Z",
        "regarding_id": 9213,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 5439,
        "date_created": "2016-09-07T05:44:25.366Z",
        "date_modified": "2016-01-08T13:28:02.269Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /activities/search?query={query}

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?query=Christa' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
Example Response
{
  "count": 25,
  "total": 806,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 446,
        "data_item": {
          "id": 5486,
          "type": "candidate"
        },
        "date": "2016-03-07T09:19:32.501Z",
        "regarding_id": 9213,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 5439,
        "date_created": "2016-09-07T05:44:25.366Z",
        "date_modified": "2016-01-08T13:28:02.269Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

Candidates

GET /candidates

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": 118,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 3460,
        "first_name": "Esteban",
        "middle_name": "Zachery",
        "last_name": "Connelly",
        "title": "National Functionality Orchestrator",
        "emails": {
          "primary": "Glen.Schowalter@gmail.com",
          "secondary": "Marcel_Hoppe90@yahoo.com"
        },
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "social_media_urls": [],
        "website": "https://aubree.biz",
        "phones": {
          "home": "(986) 885-6959",
          "cell": "(747) 789-8499",
          "work": "(700) 891-9886"
        },
        "best_time_to_call": "After 5pm",
        "current_employer": "Bergstrom, Pfeffer and Doyle",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": true,
        "key_skills": "Programming, management, fishing",
        "notes": "Consequatur magnam sequi velit repellat ut voluptates quasi nihil.",
        "source": "Google",
        "is_hot": false,
        "is_active": false,
        "contact_id": 614,
        "owner_id": 9284,
        "entered_by_id": 5403,
        "date_created": "2016-10-08T23:28:47.756Z",
        "date_modified": "2016-12-14T04:51:31.505Z",
        "_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/3460 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3460,
  "first_name": "Esteban",
  "middle_name": "Zachery",
  "last_name": "Connelly",
  "title": "National Functionality Orchestrator",
  "emails": {
    "primary": "Glen.Schowalter@gmail.com",
    "secondary": "Marcel_Hoppe90@yahoo.com"
  },
  "address": {
    "street": "37438 Alison Manor",
    "city": "East Elenabury",
    "state": "OR",
    "postal_code": "77602-4084"
  },
  "country_code": "US",
  "social_media_urls": [],
  "website": "https://aubree.biz",
  "phones": {
    "home": "(986) 885-6959",
    "cell": "(747) 789-8499",
    "work": "(700) 891-9886"
  },
  "best_time_to_call": "After 5pm",
  "current_employer": "Bergstrom, Pfeffer and Doyle",
  "date_available": "Next month",
  "current_pay": "50k",
  "desired_pay": "120k",
  "is_willing_to_relocate": true,
  "key_skills": "Programming, management, fishing",
  "notes": "Consequatur magnam sequi velit repellat ut voluptates quasi nihil.",
  "source": "Google",
  "is_hot": false,
  "is_active": false,
  "contact_id": 614,
  "owner_id": 9284,
  "entered_by_id": 5403,
  "date_created": "2016-10-08T23:28:47.756Z",
  "date_modified": "2016-12-14T04:51:31.505Z",
  "_links": {...},
  "_embedded": {...}
}

POST /candidates?check_duplicate={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

object

An object containing the email information for the candidate with the following structure:

{
  "primary": "<primary email address>",
  "secondary": "<secondary email address>"
}
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

phones

object

An object containing the phone information for the candidate with the following structure:

{
  "home": "<home phone number>",
  "cell": "<cell phone number>",
  "work": "<work phone number>"
}
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

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.

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?check_duplicate=false' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Liana","middle_name":"Adonis Bull","last_name":"O'\''Keefe","title":"Internal Directives Analyst","emails":{"primary":"Claudia.Kessler@gmail.com","secondary":"Cooper.Pagac87@gmail.com"},"address":{"street":"21342 Joanie Turnpike","city":"Karlieburgh","state":"Oregon","postal_code":"84480-1562"},"country_code":"US","social_media_urls":[],"website":"","phones":{"home":"(412) 766-3233","cell":"(536) 810-9340","work":"(301) 647-1279"},"best_time_to_call":"","current_employer":"","date_available":"","current_pay":"","desired_pay":"","is_willing_to_relocate":false,"key_skills":"","notes":"","source":"Google","is_active":true,"is_hot":false,"custom_fields":[{"id":1562,"value":"lorem"}],"work_history":[{"title":"Corporate Metrics Technician","employer":{"linked":false,"name":"Lehner and Sons","location":{"city":"West Orphamouth","state":"SD"}},"supervisor":{"linked":false,"name":"Lonny","phone":"(615) 778-7292"},"is_verified":true,"is_current":"false","start_date":"2016-08-21T14:05:01.076Z","end_date":"2016-01-08T03:18:03.557Z","reason_for_leaving":"Consequuntur itaque est."}]}'
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.

emails

object

An object containing the email information for the candidate with the following structure:

{
  "primary": "<primary email address>",
  "secondary": "<secondary email address>"
}
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

phones

object

An object containing the phone information for the candidate with the following structure:

{
  "home": "<home phone number>",
  "cell": "<cell phone number>",
  "work": "<work phone number>"
}
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

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.

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/8777 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Humberto","middle_name":"Marcos Bull","last_name":"Corkery","title":"Investor Accountability Consultant","emails":{"primary":"Gunnar.Hartmann25@yahoo.com","secondary":"Royce.Raynor70@hotmail.com"},"address":{"street":"1283 Fritsch Fork","city":"Guidoland","state":"New Jersey","postal_code":"10667-0022"},"country_code":"US","social_media_urls":[],"website":"","phones":{"home":"(272) 604-5485","cell":"(311) 253-6936","work":"(762) 301-1153"},"best_time_to_call":"","current_employer":"","date_available":"","current_pay":"","desired_pay":"","is_willing_to_relocate":false,"key_skills":"","notes":"","source":"Google","is_active":true,"is_hot":false,"custom_fields":[{"id":1562,"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/9101 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/{id}/pipelines

List pipelines

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/4024/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 224,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 5745,
        "candidate_id": 7533,
        "job_id": 6859,
        "rating": 0,
        "status_id": 4481,
        "date_created": "2016-04-19T19:38:35.637Z",
        "date_modified": "2016-09-27T02:26:14.214Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{id}/tasks

List 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/1236/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 251,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 6405,
        "data_item": {
          "id": 1490,
          "type": "candidate"
        },
        "entered_by_id": 4997,
        "assigned_to_id": 4799,
        "description": "Amet aspernatur nihil necessitatibus et.",
        "priority": 2,
        "date_due": "2016-07-20T17:35:04.225Z",
        "is_completed": true,
        "date_completed": "2016-09-15T07:02:12.215Z",
        "date_created": "2016-03-09T08:26:09.843Z",
        "date_updated": "2016-10-26T13:11:18.460Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/search?query={query}

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?query=Ludie' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 118,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 3460,
        "first_name": "Esteban",
        "middle_name": "Zachery",
        "last_name": "Connelly",
        "title": "National Functionality Orchestrator",
        "emails": {
          "primary": "Glen.Schowalter@gmail.com",
          "secondary": "Marcel_Hoppe90@yahoo.com"
        },
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "social_media_urls": [],
        "website": "https://aubree.biz",
        "phones": {
          "home": "(986) 885-6959",
          "cell": "(747) 789-8499",
          "work": "(700) 891-9886"
        },
        "best_time_to_call": "After 5pm",
        "current_employer": "Bergstrom, Pfeffer and Doyle",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": true,
        "key_skills": "Programming, management, fishing",
        "notes": "Consequatur magnam sequi velit repellat ut voluptates quasi nihil.",
        "source": "Google",
        "is_hot": false,
        "is_active": false,
        "contact_id": 614,
        "owner_id": 9284,
        "entered_by_id": 5403,
        "date_created": "2016-10-08T23:28:47.756Z",
        "date_modified": "2016-12-14T04:51:31.505Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/search?query={query}

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?query=Emmie' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
Example Response
{
  "count": 25,
  "total": 118,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 3460,
        "first_name": "Esteban",
        "middle_name": "Zachery",
        "last_name": "Connelly",
        "title": "National Functionality Orchestrator",
        "emails": {
          "primary": "Glen.Schowalter@gmail.com",
          "secondary": "Marcel_Hoppe90@yahoo.com"
        },
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "social_media_urls": [],
        "website": "https://aubree.biz",
        "phones": {
          "home": "(986) 885-6959",
          "cell": "(747) 789-8499",
          "work": "(700) 891-9886"
        },
        "best_time_to_call": "After 5pm",
        "current_employer": "Bergstrom, Pfeffer and Doyle",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": true,
        "key_skills": "Programming, management, fishing",
        "notes": "Consequatur magnam sequi velit repellat ut voluptates quasi nihil.",
        "source": "Google",
        "is_hot": false,
        "is_active": false,
        "contact_id": 614,
        "owner_id": 9284,
        "entered_by_id": 5403,
        "date_created": "2016-10-08T23:28:47.756Z",
        "date_modified": "2016-12-14T04:51:31.505Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/custom_fields

List 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": 678,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 8390,
        "data_item_type": "candidate",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /candidates/custom_fields/{id}

Get a 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/8390 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 8390,
  "data_item_type": "candidate",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /candidates/{id}/custom_fields

List 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/1445/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "673",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4087,
        "value": "herminia",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

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

Get a 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/9663/custom_fields/2732 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4087,
  "value": "herminia",
  "_links": {...},
  "_embedded": {...}
}

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

Update a 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/1038/custom_fields/9076 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"magdalena"}'
Example Response

GET /candidates/{id}/activities

List 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/7616/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 671,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 2836,
        "data_item": {
          "id": 1490,
          "type": "candidate"
        },
        "date_created": "2016-06-13T20:13:22.861Z",
        "regarding_id": 8186,
        "type": "other",
        "notes": "Added candidate to pipeline.",
        "annotation": "General",
        "entered_by_id": 5531,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/{id}/activities

Create an 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, 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/4005/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":4927,"notes":"Provident ut voluptate.","date":"2016-10-28T16:01:29.333Z"}'
Example Response

GET /candidates/{id}/attachments

List 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/820/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 153,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 3203,
        "filename": "readme.txt",
        "is_resume": true,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5557,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

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

Upload an 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/3871/attachments?filename=readme.txt' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

POST /candidates/{id}/resumes?filename={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/5188/resumes?filename=readme.txt' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /candidates/{id}/work_history

List 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/2639/work_history \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 337,
  "_links": {...},
  "_embedded": {
    "work_history": [
      {
        "id": 3460,
        "title": "Forward Operations Liason",
        "candidate_id": 8535,
        "employer": {
          "linked": false,
          "name": "Bashirian - Hilpert",
          "location": {
            "city": "East Audreannefort",
            "state": "NC"
          }
        },
        "supervisor": {
          "linked": false,
          "name": "Iva",
          "phone": "(459) 690-5547"
        },
        "is_verified": true,
        "is_current": "false",
        "start_date": "2016-01-12T11:24:27.227Z",
        "end_date": "2016-12-17T20:07:08.534Z",
        "reason_for_leaving": "Voluptatem iusto autem illo praesentium quae."
      },
      {...}
    ]
  }
}

GET /candidates/work_history/{id}

Get a work history

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/4481 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3460,
  "title": "Forward Operations Liason",
  "candidate_id": 8535,
  "employer": {
    "linked": false,
    "name": "Bashirian - Hilpert",
    "location": {
      "city": "East Audreannefort",
      "state": "NC"
    }
  },
  "supervisor": {
    "linked": false,
    "name": "Iva",
    "phone": "(459) 690-5547"
  },
  "is_verified": true,
  "is_current": "false",
  "start_date": "2016-01-12T11:24:27.227Z",
  "end_date": "2016-12-17T20:07:08.534Z",
  "reason_for_leaving": "Voluptatem iusto autem illo praesentium quae."
}

POST /candidates/{id}/work_history

Create a work history

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/3071/work_history \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Corporate Metrics Technician","employer":{"linked":false,"name":"Lehner and Sons","location":{"city":"West Orphamouth","state":"SD"}},"supervisor":{"linked":false,"name":"Lonny","phone":"(615) 778-7292"},"is_verified":true,"is_current":"false","start_date":"2016-08-21T14:05:01.076Z","end_date":"2016-01-08T03:18:03.557Z","reason_for_leaving":"Consequuntur itaque est."}'
Example Response

PUT /candidates/work_history/{id}

Update a work history

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/617 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Corporate Metrics Technician","employer":{"linked":false,"name":"Lehner and Sons","location":{"city":"West Orphamouth","state":"SD"}},"supervisor":{"linked":false,"name":"Lonny","phone":"(615) 778-7292"},"is_verified":true,"is_current":"false","start_date":"2016-08-21T14:05:01.076Z","end_date":"2016-01-08T03:18:03.557Z","reason_for_leaving":"Consequuntur itaque est."}'
Example Response

DELETE /candidates/work_history/{id}

Delete a work history

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/9888 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/lists

List all 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": 513,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 9563,
        "name": "ab",
        "notes": "Quo dolorem reiciendis.",
        "date_created": "2016-07-04T11:57:21.769Z",
        "date_modified": "2016-02-27T12:15:11.076Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/lists/{id}

Get a 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/717 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9563,
  "name": "ab",
  "notes": "Quo dolorem reiciendis.",
  "date_created": "2016-07-04T11:57:21.769Z",
  "date_modified": "2016-02-27T12:15:11.076Z",
  "_links": {...},
  "_embedded": {...}
}

POST /candidates/lists

Create a 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":"consequuntur","notes":"Sint et rerum temporibus vel sint qui blanditiis."}'
Example Response

DELETE /candidates/lists/{id}

Delete a 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/8730 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/lists/{id}/items

List all 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/2261/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 392,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 1765,
        "date_created": "2016-03-28T14:56:04.936Z",
        "candidate_id": 5110,
        "_links": {...},
        "_embedded": {
          "candidate": {
            "id": 3460,
            "first_name": "Esteban",
            "middle_name": "Zachery",
            "last_name": "Connelly",
            "title": "National Functionality Orchestrator",
            "emails": {
              "primary": "Glen.Schowalter@gmail.com",
              "secondary": "Marcel_Hoppe90@yahoo.com"
            },
            "address": {
              "street": "37438 Alison Manor",
              "city": "East Elenabury",
              "state": "OR",
              "postal_code": "77602-4084"
            },
            "country_code": "US",
            "social_media_urls": [],
            "website": "https://aubree.biz",
            "phones": {
              "home": "(986) 885-6959",
              "cell": "(747) 789-8499",
              "work": "(700) 891-9886"
            },
            "best_time_to_call": "After 5pm",
            "current_employer": "Bergstrom, Pfeffer and Doyle",
            "date_available": "Next month",
            "current_pay": "50k",
            "desired_pay": "120k",
            "is_willing_to_relocate": true,
            "key_skills": "Programming, management, fishing",
            "notes": "Consequatur magnam sequi velit repellat ut voluptates quasi nihil.",
            "source": "Google",
            "is_hot": false,
            "is_active": false,
            "contact_id": 614,
            "owner_id": 9284,
            "entered_by_id": 5403,
            "date_created": "2016-10-08T23:28:47.756Z",
            "date_modified": "2016-12-14T04:51:31.505Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a 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/4583/items/5043 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 1765,
  "date_created": "2016-03-28T14:56:04.936Z",
  "candidate_id": 5110,
  "_links": {...},
  "_embedded": {
    "candidate": {
      "id": 3460,
      "first_name": "Esteban",
      "middle_name": "Zachery",
      "last_name": "Connelly",
      "title": "National Functionality Orchestrator",
      "emails": {
        "primary": "Glen.Schowalter@gmail.com",
        "secondary": "Marcel_Hoppe90@yahoo.com"
      },
      "address": {
        "street": "37438 Alison Manor",
        "city": "East Elenabury",
        "state": "OR",
        "postal_code": "77602-4084"
      },
      "country_code": "US",
      "social_media_urls": [],
      "website": "https://aubree.biz",
      "phones": {
        "home": "(986) 885-6959",
        "cell": "(747) 789-8499",
        "work": "(700) 891-9886"
      },
      "best_time_to_call": "After 5pm",
      "current_employer": "Bergstrom, Pfeffer and Doyle",
      "date_available": "Next month",
      "current_pay": "50k",
      "desired_pay": "120k",
      "is_willing_to_relocate": true,
      "key_skills": "Programming, management, fishing",
      "notes": "Consequatur magnam sequi velit repellat ut voluptates quasi nihil.",
      "source": "Google",
      "is_hot": false,
      "is_active": false,
      "contact_id": 614,
      "owner_id": 9284,
      "entered_by_id": 5403,
      "date_created": "2016-10-08T23:28:47.756Z",
      "date_modified": "2016-12-14T04:51:31.505Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /candidates/lists/{id}/items

Create 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/9928/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"candidate_id":723}]}'
Example Response

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

Delete a 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/7401/items/8073 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/{candidate_id}/applications

List all applications

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/6816/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 687,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 7722,
        "job_id": "8869",
        "date_created": "2016-12-10T09:21:46.498Z",
        "_links": {...},
        "_embedded": {
          "fields": []
        }
      },
      {...}
    ]
  }
}

GET /candidates/applications/{application_id}

Get an 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/586 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7722,
  "job_id": "8869",
  "date_created": "2016-12-10T09:21:46.498Z",
  "_links": {...},
  "_embedded": {
    "fields": []
  }
}

GET /candidates/{candidate_id}/tags

List all 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/4259/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 429,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 4146,
        "parent_id": 225,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/{candidate_id}/tags

Replace 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/4315/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

PUT /candidates/{candidate_id}/tags

Attach 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/297/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

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

Delete 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/3998/tags/9107 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /candidates/{id}/thumbnail

Get a 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/4327/thumbnail \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "source": "attachment",
  "attachment_id": 9280,
  "url": "http://morgan.name",
  "_links": {...}
}

PUT /candidates/{id}/thumbnail

Change a 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/6788/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":6668}'
Example Response

Contacts

GET /contacts

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": 832,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 4128,
        "first_name": "Unique",
        "last_name": "Cassin",
        "title": "Legacy Mobility Engineer",
        "reports_to_id": 3030,
        "emails": {
          "primary": "Emilio_Bartoletti87@hotmail.com",
          "secondary": "Adelle51@yahoo.com"
        },
        "phones": {
          "cell": "(768) 691-3899",
          "work": "(218) 441-2100",
          "other": "(606) 472-9803"
        },
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "social_media_urls": [],
        "is_hot": false,
        "notes": "Dicta amet sed expedita totam voluptatem similique dolor in.",
        "entered_by_id": 5783,
        "status_id": 799,
        "date_created": "2016-12-30T13:41:40.644Z",
        "date_modified": "2016-09-24T16:57:34.883Z",
        "_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/4128 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4128,
  "first_name": "Unique",
  "last_name": "Cassin",
  "title": "Legacy Mobility Engineer",
  "reports_to_id": 3030,
  "emails": {
    "primary": "Emilio_Bartoletti87@hotmail.com",
    "secondary": "Adelle51@yahoo.com"
  },
  "phones": {
    "cell": "(768) 691-3899",
    "work": "(218) 441-2100",
    "other": "(606) 472-9803"
  },
  "address": {
    "street": "37438 Alison Manor",
    "city": "East Elenabury",
    "state": "OR",
    "postal_code": "77602-4084"
  },
  "country_code": "US",
  "social_media_urls": [],
  "is_hot": false,
  "notes": "Dicta amet sed expedita totam voluptatem similique dolor in.",
  "entered_by_id": 5783,
  "status_id": 799,
  "date_created": "2016-12-30T13:41:40.644Z",
  "date_modified": "2016-09-24T16:57:34.883Z",
  "_links": {...},
  "_embedded": {...}
}

POST /contacts?check_duplicate={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.

emails

object

An object containing the email information for the contact with the following structure:

{
  "primary": "<primary email address>",
  "secondary": "<secondary email address>"
}
phones

object

An object containing the phone information for the contact with the following structure:

{
  "work": "<work phone number>",
  "cell": "<cell phone number>",
  "other": "<other phone number>"
}
has_left_company

boolean

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?check_duplicate=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Vinnie","last_name":"Schoen","owner_id":6597,"company_id":1403,"title":"Dynamic Brand Director","reports_to_id":2601,"emails":{"primary":"Ricky.Leuschke97@hotmail.com","secondary":"Rebeka_Pagac@hotmail.com"},"phones":{"work":"(883) 684-8496","cell":"(558) 512-1754","other":"(474) 540-3098"},"has_left_company":true,"address":{"street":"6721 Murray Lodge","city":"Averyfort","state":"Tennessee","postal_code":"26586-6856"},"country_code":"US","social_media_urls":[],"is_hot":false,"notes":"Veritatis distinctio animi voluptatem aut incidunt id vitae a accusantium.","custom_fields":[{"id":1562,"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.

emails

object

An object containing the email information for the contact with the following structure:

{
  "primary": "<primary email address>",
  "secondary": "<secondary email address>"
}
phones

object

An object containing the phone information for the contact with the following structure:

{
  "work": "<work phone number>",
  "cell": "<cell phone number>",
  "other": "<other phone number>"
}
has_left_company

boolean

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/9667 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Vinnie","last_name":"Schoen","owner_id":6597,"company_id":1403,"title":"Dynamic Brand Director","reports_to_id":2601,"emails":{"primary":"Ricky.Leuschke97@hotmail.com","secondary":"Rebeka_Pagac@hotmail.com"},"phones":{"work":"(883) 684-8496","cell":"(558) 512-1754","other":"(474) 540-3098"},"has_left_company":true,"address":{"street":"6721 Murray Lodge","city":"Averyfort","state":"Tennessee","postal_code":"26586-6856"},"country_code":"US","social_media_urls":[],"is_hot":false,"notes":"Veritatis distinctio animi voluptatem aut incidunt id vitae a accusantium.","custom_fields":[{"id":1562,"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/1813 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{id}/tasks

List 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/6762/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 981,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 6405,
        "data_item": {
          "id": 5423,
          "type": "contact"
        },
        "entered_by_id": 4322,
        "assigned_to_id": 7448,
        "description": "Quis dicta deserunt et dolore iste.",
        "priority": 2,
        "date_due": "2016-07-07T22:27:52.151Z",
        "is_completed": true,
        "date_completed": "2016-07-29T04:10:33.426Z",
        "date_created": "2016-04-28T11:43:44.456Z",
        "date_updated": "2016-04-01T03:14:43.467Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/search?query={query}

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?query=Hailee' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 832,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 4128,
        "first_name": "Unique",
        "last_name": "Cassin",
        "title": "Legacy Mobility Engineer",
        "reports_to_id": 3030,
        "emails": {
          "primary": "Emilio_Bartoletti87@hotmail.com",
          "secondary": "Adelle51@yahoo.com"
        },
        "phones": {
          "cell": "(768) 691-3899",
          "work": "(218) 441-2100",
          "other": "(606) 472-9803"
        },
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "social_media_urls": [],
        "is_hot": false,
        "notes": "Dicta amet sed expedita totam voluptatem similique dolor in.",
        "entered_by_id": 5783,
        "status_id": 799,
        "date_created": "2016-12-30T13:41:40.644Z",
        "date_modified": "2016-09-24T16:57:34.883Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/search?query={query}

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?query=Leonie' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
Example Response
{
  "count": 25,
  "total": 832,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 4128,
        "first_name": "Unique",
        "last_name": "Cassin",
        "title": "Legacy Mobility Engineer",
        "reports_to_id": 3030,
        "emails": {
          "primary": "Emilio_Bartoletti87@hotmail.com",
          "secondary": "Adelle51@yahoo.com"
        },
        "phones": {
          "cell": "(768) 691-3899",
          "work": "(218) 441-2100",
          "other": "(606) 472-9803"
        },
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "social_media_urls": [],
        "is_hot": false,
        "notes": "Dicta amet sed expedita totam voluptatem similique dolor in.",
        "entered_by_id": 5783,
        "status_id": 799,
        "date_created": "2016-12-30T13:41:40.644Z",
        "date_modified": "2016-09-24T16:57:34.883Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/custom_fields

List 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": 713,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 8390,
        "data_item_type": "contact",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /contacts/custom_fields/{id}

Get a 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/8390 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 8390,
  "data_item_type": "contact",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /contacts/{id}/custom_fields

List 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/6936/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "673",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4087,
        "value": "herminia",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

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

Get a 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/3705/custom_fields/7090 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4087,
  "value": "herminia",
  "_links": {...},
  "_embedded": {...}
}

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

Update a 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/3505/custom_fields/3992 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"magdalena"}'
Example Response

GET /contacts/{id}/activities

List 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/8220/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 732,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 2529,
        "data_item": {
          "id": 5423,
          "type": "contact"
        },
        "date_created": "2016-06-21T23:37:27.470Z",
        "regarding_id": 1705,
        "type": "type_other",
        "notes": "Added candidate to pipeline.",
        "annotation": "General",
        "entered_by_id": 5732,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/{id}/activities

Create an 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, 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/6319/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":4927,"notes":"Provident ut voluptate.","date":"2016-10-28T16:01:29.333Z"}'
Example Response

GET /contacts/statuses

List 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": 446,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4526,
        "title": "Employee",
        "mapping": "human_resources",
        "prerequisites": [
          {
            "id": 3317
          }
        ],
        "triggers": [
          {
            "id": 4430
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /contacts/statuses/{id}

Get a status

Parameters
id

required

string

The ID of the status to return.

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

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

Change 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/8714/status?create_activity=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":4251,"triggers":[{"id":2675,"fire":false}]}'
Example Response

GET /contacts/{id}/attachments

List 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/9782/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 153,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 3203,
        "filename": "readme.txt",
        "is_resume": true,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5557,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

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

Upload an 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/3477/attachments?filename=readme.txt' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /contacts/lists

List all 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": 513,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 9563,
        "name": "ab",
        "notes": "Quo dolorem reiciendis.",
        "date_created": "2016-07-04T11:57:21.769Z",
        "date_modified": "2016-02-27T12:15:11.076Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/lists/{id}

Get a 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/6507 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9563,
  "name": "ab",
  "notes": "Quo dolorem reiciendis.",
  "date_created": "2016-07-04T11:57:21.769Z",
  "date_modified": "2016-02-27T12:15:11.076Z",
  "_links": {...},
  "_embedded": {...}
}

POST /contacts/lists

Create a 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":"consequuntur","notes":"Sint et rerum temporibus vel sint qui blanditiis."}'
Example Response

DELETE /contacts/lists/{id}

Delete a 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/5572 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/lists/{id}/items

List all 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/5055/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 241,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 5594,
        "date_created": "2016-05-13T15:49:38.305Z",
        "contact_id": 2577,
        "_links": {...},
        "_embedded": {
          "contact": {
            "id": 4128,
            "first_name": "Unique",
            "last_name": "Cassin",
            "title": "Legacy Mobility Engineer",
            "reports_to_id": 3030,
            "emails": {
              "primary": "Emilio_Bartoletti87@hotmail.com",
              "secondary": "Adelle51@yahoo.com"
            },
            "phones": {
              "cell": "(768) 691-3899",
              "work": "(218) 441-2100",
              "other": "(606) 472-9803"
            },
            "address": {
              "street": "37438 Alison Manor",
              "city": "East Elenabury",
              "state": "OR",
              "postal_code": "77602-4084"
            },
            "country_code": "US",
            "social_media_urls": [],
            "is_hot": false,
            "notes": "Dicta amet sed expedita totam voluptatem similique dolor in.",
            "entered_by_id": 5783,
            "status_id": 799,
            "date_created": "2016-12-30T13:41:40.644Z",
            "date_modified": "2016-09-24T16:57:34.883Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a 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/4663/items/7195 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5594,
  "date_created": "2016-05-13T15:49:38.305Z",
  "contact_id": 2577,
  "_links": {...},
  "_embedded": {
    "contact": {
      "id": 4128,
      "first_name": "Unique",
      "last_name": "Cassin",
      "title": "Legacy Mobility Engineer",
      "reports_to_id": 3030,
      "emails": {
        "primary": "Emilio_Bartoletti87@hotmail.com",
        "secondary": "Adelle51@yahoo.com"
      },
      "phones": {
        "cell": "(768) 691-3899",
        "work": "(218) 441-2100",
        "other": "(606) 472-9803"
      },
      "address": {
        "street": "37438 Alison Manor",
        "city": "East Elenabury",
        "state": "OR",
        "postal_code": "77602-4084"
      },
      "country_code": "US",
      "social_media_urls": [],
      "is_hot": false,
      "notes": "Dicta amet sed expedita totam voluptatem similique dolor in.",
      "entered_by_id": 5783,
      "status_id": 799,
      "date_created": "2016-12-30T13:41:40.644Z",
      "date_modified": "2016-09-24T16:57:34.883Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /contacts/lists/{id}/items

Create 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/9464/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"contact_id":3158}]}'
Example Response

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

Delete a 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/2522/items/4350 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{contact_id}/tags

List all 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/9644/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 429,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 4146,
        "parent_id": 225,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/{contact_id}/tags

Replace 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/5685/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

PUT /contacts/{contact_id}/tags

Attach 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/4866/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

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

Delete 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/9581/tags/6703 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /contacts/{id}/thumbnail

Get a 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/8941/thumbnail \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "source": "attachment",
  "attachment_id": 9280,
  "url": "http://morgan.name",
  "_links": {...}
}

PUT /contacts/{id}/thumbnail

Change a 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/7517/thumbnail \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"source":"attachment","attachment_id":6668}'
Example Response

Companies

GET /companies

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": 228,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 2343,
        "owner_id": 6701,
        "name": "Padberg - Skiles",
        "website": "https://helena.com",
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "phones": {
          "primary": "(780) 610-9126",
          "secondary": "(975) 847-6026",
          "fax": "(842) 724-5605"
        },
        "entered_by_id": 6148,
        "social_media_urls": [],
        "notes": "Praesentium reiciendis dicta.",
        "is_hot": false,
        "key_technologies": "",
        "billing_contact_id": 2644,
        "status_id": 484,
        "date_created": "2016-06-11T15:17:15.053Z",
        "date_modified": "2016-05-21T21:22:42.506Z",
        "_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/2343 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2343,
  "owner_id": 6701,
  "name": "Padberg - Skiles",
  "website": "https://helena.com",
  "address": {
    "street": "37438 Alison Manor",
    "city": "East Elenabury",
    "state": "OR",
    "postal_code": "77602-4084"
  },
  "country_code": "US",
  "phones": {
    "primary": "(780) 610-9126",
    "secondary": "(975) 847-6026",
    "fax": "(842) 724-5605"
  },
  "entered_by_id": 6148,
  "social_media_urls": [],
  "notes": "Praesentium reiciendis dicta.",
  "is_hot": false,
  "key_technologies": "",
  "billing_contact_id": 2644,
  "status_id": 484,
  "date_created": "2016-06-11T15:17:15.053Z",
  "date_modified": "2016-05-21T21:22:42.506Z",
  "_links": {...},
  "_embedded": {...}
}

POST /companies?check_duplicate={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

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

phones

object

An object containing the contact numbers for the company with the following structure:

{
  "primary": "<primary phone number>",
  "secondary": "<secondary phone number>",
  "fax": "<fax phone number>"
}
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>"
    }
]
Example Request
curl -X POST \
'https://api.catsone.com/v3/companies?check_duplicate=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Rempel, Blick and Bosco","owner_id":3671,"website":"http://baron.name","address":{"street":"4073 Langworth Mountains","city":"East Tess","state":"New York","postal_code":"67463"},"country_code":"US","phones":{"primary":"(774) 889-1497","secondary":"(244) 491-7358","fax":"(264) 286-7886"},"entered_by_id":8155,"social_media_urls":[],"notes":"Nihil aut nesciunt placeat repellendus tempore quia consectetur.","is_hot":true,"key_technologies":"","billing_contact_id":3979,"custom_fields":[{"id":1562,"value":"lorem"}]}'
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

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

phones

object

An object containing the contact numbers for the company with the following structure:

{
  "primary": "<primary phone number>",
  "secondary": "<secondary phone number>",
  "fax": "<fax phone number>"
}
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>"
    }
]
Example Request
curl -X PUT \
https://api.catsone.com/v3/companies/507 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Rempel, Blick and Bosco","owner_id":3671,"website":"http://baron.name","address":{"street":"4073 Langworth Mountains","city":"East Tess","state":"New York","postal_code":"67463"},"country_code":"US","phones":{"primary":"(774) 889-1497","secondary":"(244) 491-7358","fax":"(264) 286-7886"},"entered_by_id":8155,"social_media_urls":[],"notes":"Nihil aut nesciunt placeat repellendus tempore quia consectetur.","is_hot":true,"key_technologies":"","billing_contact_id":3979,"custom_fields":[{"id":1562,"value":"lorem"}]}'
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/3181 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{id}/tasks

List 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/3611/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 998,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 6405,
        "data_item": {
          "id": 308,
          "type": "company"
        },
        "entered_by_id": 5239,
        "assigned_to_id": 9332,
        "description": "Vel officiis id cumque laborum sint.",
        "priority": 2,
        "date_due": "2016-01-07T10:08:44.150Z",
        "is_completed": true,
        "date_completed": "2016-06-19T08:54:40.604Z",
        "date_created": "2016-03-29T06:54:37.024Z",
        "date_updated": "2016-09-06T23:26:05.109Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/search?query={query}

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?query=Betty' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 228,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 2343,
        "owner_id": 6701,
        "name": "Padberg - Skiles",
        "website": "https://helena.com",
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "phones": {
          "primary": "(780) 610-9126",
          "secondary": "(975) 847-6026",
          "fax": "(842) 724-5605"
        },
        "entered_by_id": 6148,
        "social_media_urls": [],
        "notes": "Praesentium reiciendis dicta.",
        "is_hot": false,
        "key_technologies": "",
        "billing_contact_id": 2644,
        "status_id": 484,
        "date_created": "2016-06-11T15:17:15.053Z",
        "date_modified": "2016-05-21T21:22:42.506Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /companies/search?query={query}

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?query=Felicia' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
Example Response
{
  "count": 25,
  "total": 228,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 2343,
        "owner_id": 6701,
        "name": "Padberg - Skiles",
        "website": "https://helena.com",
        "address": {
          "street": "37438 Alison Manor",
          "city": "East Elenabury",
          "state": "OR",
          "postal_code": "77602-4084"
        },
        "country_code": "US",
        "phones": {
          "primary": "(780) 610-9126",
          "secondary": "(975) 847-6026",
          "fax": "(842) 724-5605"
        },
        "entered_by_id": 6148,
        "social_media_urls": [],
        "notes": "Praesentium reiciendis dicta.",
        "is_hot": false,
        "key_technologies": "",
        "billing_contact_id": 2644,
        "status_id": 484,
        "date_created": "2016-06-11T15:17:15.053Z",
        "date_modified": "2016-05-21T21:22:42.506Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/custom_fields

List 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": 138,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 8390,
        "data_item_type": "company",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /companies/custom_fields/{id}

Get a 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/8390 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 8390,
  "data_item_type": "company",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /companies/{id}/custom_fields

List 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/2734/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "673",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4087,
        "value": "herminia",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

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

Get a 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/8718/custom_fields/9536 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4087,
  "value": "herminia",
  "_links": {...},
  "_embedded": {...}
}

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

Update a 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/1819/custom_fields/6284 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"magdalena"}'
Example Response

GET /companies/statuses

List 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": 663,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4526,
        "title": "Lead",
        "mapping": "lead",
        "prerequisites": [
          {
            "id": 3317
          }
        ],
        "triggers": [
          {
            "id": 4430
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /companies/statuses/{id}

Get a status

Parameters
id

required

string

The ID of the status to return.

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

POST /companies/{id}/status

Change 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/9139/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":4251,"triggers":[{"id":2675,"fire":false}]}'
Example Response

GET /companies/{id}/attachments

List 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/2479/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 153,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 3203,
        "filename": "readme.txt",
        "is_resume": true,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5557,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

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

Upload an 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/3779/attachments?filename=readme.txt' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /companies/lists

List all 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": 513,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 9563,
        "name": "ab",
        "notes": "Quo dolorem reiciendis.",
        "date_created": "2016-07-04T11:57:21.769Z",
        "date_modified": "2016-02-27T12:15:11.076Z",
        "_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/7689 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9563,
  "name": "ab",
  "notes": "Quo dolorem reiciendis.",
  "date_created": "2016-07-04T11:57:21.769Z",
  "date_modified": "2016-02-27T12:15:11.076Z",
  "_links": {...},
  "_embedded": {...}
}

POST /companies/lists

Create a 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":"consequuntur","notes":"Sint et rerum temporibus vel sint qui blanditiis."}'
Example Response

DELETE /companies/lists/{id}

Delete a 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/318 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/lists/{id}/items

List all 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/3032/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 220,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 2179,
        "date_created": "2016-01-30T08:01:11.902Z",
        "company_id": 9262,
        "_links": {...},
        "_embedded": {
          "company": {
            "id": 2343,
            "owner_id": 6701,
            "name": "Padberg - Skiles",
            "website": "https://helena.com",
            "address": {
              "street": "37438 Alison Manor",
              "city": "East Elenabury",
              "state": "OR",
              "postal_code": "77602-4084"
            },
            "country_code": "US",
            "phones": {
              "primary": "(780) 610-9126",
              "secondary": "(975) 847-6026",
              "fax": "(842) 724-5605"
            },
            "entered_by_id": 6148,
            "social_media_urls": [],
            "notes": "Praesentium reiciendis dicta.",
            "is_hot": false,
            "key_technologies": "",
            "billing_contact_id": 2644,
            "status_id": 484,
            "date_created": "2016-06-11T15:17:15.053Z",
            "date_modified": "2016-05-21T21:22:42.506Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a 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/2063/items/6975 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2179,
  "date_created": "2016-01-30T08:01:11.902Z",
  "company_id": 9262,
  "_links": {...},
  "_embedded": {
    "company": {
      "id": 2343,
      "owner_id": 6701,
      "name": "Padberg - Skiles",
      "website": "https://helena.com",
      "address": {
        "street": "37438 Alison Manor",
        "city": "East Elenabury",
        "state": "OR",
        "postal_code": "77602-4084"
      },
      "country_code": "US",
      "phones": {
        "primary": "(780) 610-9126",
        "secondary": "(975) 847-6026",
        "fax": "(842) 724-5605"
      },
      "entered_by_id": 6148,
      "social_media_urls": [],
      "notes": "Praesentium reiciendis dicta.",
      "is_hot": false,
      "key_technologies": "",
      "billing_contact_id": 2644,
      "status_id": 484,
      "date_created": "2016-06-11T15:17:15.053Z",
      "date_modified": "2016-05-21T21:22:42.506Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /companies/lists/{id}/items

Create 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/1346/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"company_id":9050}]}'
Example Response

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

Delete a 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/602/items/5584 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{company_id}/tags

List all 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/599/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 429,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 4146,
        "parent_id": 225,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /companies/{company_id}/tags

Replace 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/2392/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

PUT /companies/{company_id}/tags

Attach 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/4009/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

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

Delete 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/749/tags/7983 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{company_id}/departments

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/7117/departments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 785,
  "_links": {...},
  "_embedded": {
    "departments": [
      {
        "id": 8670,
        "name": "Fahey LLC",
        "_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/8670 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 8670,
  "name": "Fahey LLC",
  "_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/8352/departments \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Schamberger, Schiller and McLaughlin"}'
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/1641 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Schamberger, Schiller and McLaughlin"}'
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/2641 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /companies/{id}/thumbnail

Get a 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/1036/thumbnail \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "source": "attachment",
  "attachment_id": 9280,
  "url": "http://morgan.name",
  "_links": {...}
}

PUT /companies/{id}/thumbnail

Change a 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)

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

Jobs

GET /jobs

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": 625,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 4281,
        "title": "Corporate Metrics Planner",
        "location": {
          "city": "Marilouton",
          "state": "NC",
          "postal_code": "84225-2810"
        },
        "country_code": "US",
        "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
        "notes": "Alias totam aperiam veniam veritatis porro earum.",
        "recruiter_id": 6391,
        "owner_id": 7106,
        "category": null,
        "is_hot": true,
        "start_date": "2016-07-28T17:15:13.130Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5854,
        "department_id": 530,
        "status_id": 8455,
        "workflow_id": 7490,
        "date_created": "2016-06-29T16:35:00.774Z",
        "date_modified": "2016-01-19T09:10:44.326Z",
        "_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/4281 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4281,
  "title": "Corporate Metrics Planner",
  "location": {
    "city": "Marilouton",
    "state": "NC",
    "postal_code": "84225-2810"
  },
  "country_code": "US",
  "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
  "notes": "Alias totam aperiam veniam veritatis porro earum.",
  "recruiter_id": 6391,
  "owner_id": 7106,
  "category": null,
  "is_hot": true,
  "start_date": "2016-07-28T17:15:13.130Z",
  "salary": null,
  "max_rate": null,
  "duration": "",
  "external_id": null,
  "company_id": 5854,
  "department_id": 530,
  "status_id": 8455,
  "workflow_id": 7490,
  "date_created": "2016-06-29T16:35:00.774Z",
  "date_modified": "2016-01-19T09:10:44.326Z",
  "_links": {...},
  "_embedded": {...}
}

POST /jobs?check_duplicate={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.

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>"
    }
]
Example Request
curl -X POST \
'https://api.catsone.com/v3/jobs?check_duplicate=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Senior Infrastructure Technician","location":{"city":"Jackelinemouth","state":"CT","postal_code":"52104-5262"},"country_code":"US","company_id":4480,"department_id":2806,"recruiter_id":1455,"category_name":"","is_hot":false,"start_date":"2016-11-22T05:24:09.857Z","salary":"","max_rate":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":8893,"workflow_id":4857,"custom_fields":[{"id":1562,"value":"lorem"}]}'
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.

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>"
    }
]
Example Request
curl -X PUT \
https://api.catsone.com/v3/jobs/1081 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Chief Division Architect","location":{"city":"South Giles","state":"FL","postal_code":"57828"},"country_code":"US","company_id":6912,"department_id":5584,"recruiter_id":4820,"category_name":"","is_hot":true,"start_date":"2016-10-12T01:20:25.037Z","salary":"","max_rate":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":923,"custom_fields":[{"id":1562,"value":"lorem"}]}'
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/7182 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /jobs/{id}/pipelines

List pipelines

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/7022/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 224,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 5745,
        "candidate_id": 7533,
        "job_id": 6859,
        "rating": 0,
        "status_id": 4481,
        "date_created": "2016-04-19T19:38:35.637Z",
        "date_modified": "2016-09-27T02:26:14.214Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{job_id}/applications

List applications

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/jobs/%7Bjob_id%7D/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 759,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 7722,
        "description": "Quos ut consequatur consequatur exercitationem nulla dolor.",
        "header": "Qui ipsa possimus aspernatur quia voluptatem.",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{id}/tasks

List 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/813/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 478,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 6405,
        "data_item": {
          "id": 6830,
          "type": "job"
        },
        "entered_by_id": 7089,
        "assigned_to_id": 4614,
        "description": "Accusantium et labore sunt qui assumenda ullam.",
        "priority": 2,
        "date_due": "2016-04-29T22:58:59.431Z",
        "is_completed": true,
        "date_completed": "2016-11-01T13:48:44.988Z",
        "date_created": "2016-10-30T17:02:47.796Z",
        "date_updated": "2016-07-22T12:30:14.539Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/search?query={query}

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?query=Aisha' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 625,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 4281,
        "title": "Corporate Metrics Planner",
        "location": {
          "city": "Marilouton",
          "state": "NC",
          "postal_code": "84225-2810"
        },
        "country_code": "US",
        "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
        "notes": "Alias totam aperiam veniam veritatis porro earum.",
        "recruiter_id": 6391,
        "owner_id": 7106,
        "category": null,
        "is_hot": true,
        "start_date": "2016-07-28T17:15:13.130Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5854,
        "department_id": 530,
        "status_id": 8455,
        "workflow_id": 7490,
        "date_created": "2016-06-29T16:35:00.774Z",
        "date_modified": "2016-01-19T09:10:44.326Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /jobs/search?query={query}

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?query=Ramona' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"field":"notes","filter":"contains","value":"rejected"}'
Example Response
{
  "count": 25,
  "total": 625,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 4281,
        "title": "Corporate Metrics Planner",
        "location": {
          "city": "Marilouton",
          "state": "NC",
          "postal_code": "84225-2810"
        },
        "country_code": "US",
        "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
        "notes": "Alias totam aperiam veniam veritatis porro earum.",
        "recruiter_id": 6391,
        "owner_id": 7106,
        "category": null,
        "is_hot": true,
        "start_date": "2016-07-28T17:15:13.130Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5854,
        "department_id": 530,
        "status_id": 8455,
        "workflow_id": 7490,
        "date_created": "2016-06-29T16:35:00.774Z",
        "date_modified": "2016-01-19T09:10:44.326Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/custom_fields

List 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": 334,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 8390,
        "data_item_type": "job",
        "name": "Favorite Color",
        "comment": "",
        "field": {
          "type": "text"
        }
      },
      {...}
    ]
  }
}

GET /jobs/custom_fields/{id}

Get a 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/8390 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 8390,
  "data_item_type": "job",
  "name": "Favorite Color",
  "comment": "",
  "field": {
    "type": "text"
  }
}

GET /jobs/{id}/custom_fields

List 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/7764/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "673",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 4087,
        "value": "herminia",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

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

Get a 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/9148/custom_fields/537 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4087,
  "value": "herminia",
  "_links": {...},
  "_embedded": {...}
}

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

Update a 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/5581/custom_fields/5750 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"value":"magdalena"}'
Example Response

GET /jobs/statuses

List 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": 922,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4526,
        "title": "Active",
        "mapping": 0,
        "prerequisites": [
          {
            "id": 3317
          }
        ],
        "triggers": [
          {
            "id": 4430
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /jobs/statuses/{id}

Get a status

Parameters
id

required

string

The ID of the status to return.

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

POST /jobs/{id}/status

Change 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/6146/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":4251,"triggers":[{"id":2675,"fire":false}]}'
Example Response

GET /jobs/{id}/attachments

List 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/9081/attachments \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 153,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 3203,
        "filename": "readme.txt",
        "is_resume": true,
        "size": "",
        "version": "",
        "data_item": {
          "id": 5557,
          "type": "candidate"
        }
      },
      {...}
    ]
  }
}

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

Upload an 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/5493/attachments?filename=readme.txt' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/octet-stream' \
--data-binary @filename.txt
Example Response

GET /jobs/lists

List all 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": 513,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 9563,
        "name": "ab",
        "notes": "Quo dolorem reiciendis.",
        "date_created": "2016-07-04T11:57:21.769Z",
        "date_modified": "2016-02-27T12:15:11.076Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/lists/{id}

Get a 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/9438 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9563,
  "name": "ab",
  "notes": "Quo dolorem reiciendis.",
  "date_created": "2016-07-04T11:57:21.769Z",
  "date_modified": "2016-02-27T12:15:11.076Z",
  "_links": {...},
  "_embedded": {...}
}

POST /jobs/lists

Create a 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":"consequuntur","notes":"Sint et rerum temporibus vel sint qui blanditiis."}'
Example Response

DELETE /jobs/lists/{id}

Delete a 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/9718 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /jobs/lists/{id}/items

List all 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/9515/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 268,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 3728,
        "date_created": "2016-09-10T10:04:11.686Z",
        "job_id": 4775,
        "_links": {...},
        "_embedded": {
          "job": {
            "id": 4281,
            "title": "Corporate Metrics Planner",
            "location": {
              "city": "Marilouton",
              "state": "NC",
              "postal_code": "84225-2810"
            },
            "country_code": "US",
            "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
            "notes": "Alias totam aperiam veniam veritatis porro earum.",
            "recruiter_id": 6391,
            "owner_id": 7106,
            "category": null,
            "is_hot": true,
            "start_date": "2016-07-28T17:15:13.130Z",
            "salary": null,
            "max_rate": null,
            "duration": "",
            "external_id": null,
            "company_id": 5854,
            "department_id": 530,
            "status_id": 8455,
            "workflow_id": 7490,
            "date_created": "2016-06-29T16:35:00.774Z",
            "date_modified": "2016-01-19T09:10:44.326Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a 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/2639/items/4753 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3728,
  "date_created": "2016-09-10T10:04:11.686Z",
  "job_id": 4775,
  "_links": {...},
  "_embedded": {
    "job": {
      "id": 4281,
      "title": "Corporate Metrics Planner",
      "location": {
        "city": "Marilouton",
        "state": "NC",
        "postal_code": "84225-2810"
      },
      "country_code": "US",
      "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
      "notes": "Alias totam aperiam veniam veritatis porro earum.",
      "recruiter_id": 6391,
      "owner_id": 7106,
      "category": null,
      "is_hot": true,
      "start_date": "2016-07-28T17:15:13.130Z",
      "salary": null,
      "max_rate": null,
      "duration": "",
      "external_id": null,
      "company_id": 5854,
      "department_id": 530,
      "status_id": 8455,
      "workflow_id": 7490,
      "date_created": "2016-06-29T16:35:00.774Z",
      "date_modified": "2016-01-19T09:10:44.326Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /jobs/lists/{id}/items

Create 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/7243/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"items":[{"job_id":1082}]}'
Example Response

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

Delete a 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/186/items/1867 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /jobs/{job_id}/applications

List applications

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/4923/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 759,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 7722,
        "description": "Quos ut consequatur consequatur exercitationem nulla dolor.",
        "header": "Qui ipsa possimus aspernatur quia voluptatem.",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/applications/{application_id}

Get an 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/883 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7722,
  "description": "Quos ut consequatur consequatur exercitationem nulla dolor.",
  "header": "Qui ipsa possimus aspernatur quia voluptatem.",
  "_links": {...},
  "_embedded": {...}
}

GET /jobs/applications/{application_id}/fields

List 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/9546/fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 571,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 6465,
        "title": "Hic velit labore sed eius maiores.",
        "position": 0,
        "type": "text",
        "answers": [],
        "is_required": false,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{job_id}/tags

List all 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/4991/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 429,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 4146,
        "parent_id": 225,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /jobs/{job_id}/tags

Replace 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/8016/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

PUT /jobs/{job_id}/tags

Attach 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/9852/tags \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"tags":[{"id":1101}]}'
Example Response

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

Delete 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/7683/tags/6187 \
-H 'authorization: Token <Your API Key>'
Example Response

Users

GET /users

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": 1340,
        "username": "Newton36@yahoo.com",
        "first_name": "Esther",
        "last_name": "Dicki",
        "title": "Investor Markets Planner",
        "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/1340 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 1340,
  "username": "Newton36@yahoo.com",
  "first_name": "Esther",
  "last_name": "Dicki",
  "title": "Investor Markets Planner",
  "access_level: add_edit_delete": "",
  "_links": {...}
}

Pipelines

GET /pipelines

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": 224,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 5745,
        "candidate_id": 7533,
        "job_id": 6859,
        "rating": 0,
        "status_id": 4481,
        "date_created": "2016-04-19T19:38:35.637Z",
        "date_modified": "2016-09-27T02:26:14.214Z",
        "_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/5745 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5745,
  "candidate_id": 7533,
  "job_id": 6859,
  "rating": 0,
  "status_id": 4481,
  "date_created": "2016-04-19T19:38:35.637Z",
  "date_modified": "2016-09-27T02:26:14.214Z",
  "_links": {...},
  "_embedded": {...}
}

POST /pipelines?create_activity=true

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?create_activity=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"candidate_id":544,"job_id":6329,"rating":2}'
Example Response

PUT /pipelines/{id}

Update a pipeline

Parameters
id

required

string

The ID of the pipeline to update.

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 PUT \
https://api.catsone.com/v3/pipelines/5029 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"candidate_id":544,"job_id":6329,"rating":2}'
Example Response

DELETE /pipeline/{id}?create_activity=true

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/1756?create_activity=true' \
-H 'authorization: Token <Your API Key>'
Example Response

POST /pipelines/search

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": 224,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 5745,
        "candidate_id": 7533,
        "job_id": 6859,
        "rating": 0,
        "status_id": 4481,
        "date_created": "2016-04-19T19:38:35.637Z",
        "date_modified": "2016-09-27T02:26:14.214Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /pipelines/workflows

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": 1340,
        "title": "Nesciunt natus occaecati et et.",
        "is_default": true,
        "date_modified": "2016-03-02T13:59:45.619Z",
        "_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/6834 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 1340,
  "title": "Nesciunt natus occaecati et et.",
  "is_default": true,
  "date_modified": "2016-03-02T13:59:45.619Z",
  "_links": {...},
  "_embedded": {...}
}

GET /pipelines/workflow/{workflow_id}/statuses

List 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/6834/statuses \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 220,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 4526,
        "title": "Offered",
        "mapping": 0,
        "prerequisites": [
          {
            "id": 3317
          }
        ],
        "triggers": [
          {
            "id": 4430
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

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

Get a 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/6834/statuses/4526 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4526,
  "title": "Offered",
  "mapping": 0,
  "prerequisites": [
    {
      "id": 3317
    }
  ],
  "triggers": [
    {
      "id": 4430
    }
  ],
  "_links": {...}
}

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

Change 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/2014/status?create_activity=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":4251,"triggers":[{"id":2675,"fire":false}]}'
Example Response

Tasks

GET /tasks

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": 562,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 6405,
        "data_item": {
          "id": 5486,
          "type": "candidate"
        },
        "entered_by_id": 2167,
        "assigned_to_id": 1255,
        "description": "Culpa facilis voluptatem accusantium debitis animi.",
        "priority": 2,
        "date_due": "2016-06-17T05:57:18.827Z",
        "is_completed": true,
        "date_completed": "2016-05-26T15:20:48.914Z",
        "date_created": "2016-02-12T10:43:24.173Z",
        "date_updated": "2016-08-13T04:48:32.741Z",
        "_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/6405 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6405,
  "data_item": {
    "id": 5486,
    "type": "candidate"
  },
  "entered_by_id": 2167,
  "assigned_to_id": 1255,
  "description": "Culpa facilis voluptatem accusantium debitis animi.",
  "priority": 2,
  "date_due": "2016-06-17T05:57:18.827Z",
  "is_completed": true,
  "date_completed": "2016-05-26T15:20:48.914Z",
  "date_created": "2016-02-12T10:43:24.173Z",
  "date_updated": "2016-08-13T04:48:32.741Z",
  "_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":5486,"type":"candidate"},"assigned_to_id":6886,"description":"Aut voluptas itaque aut.","priority":3,"date_due":"2016-05-16T11:38:10.979Z"}'
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/713 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"assigned_to_id":4960,"description":"Quo ea asperiores.","priority":3,"date_due":"2016-08-15T07:57:46.525Z","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/8811 \
-H 'authorization: Token <Your API Key>'
Example Response

Triggers

GET /triggers

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": 642,
  "_links": {...},
  "_embedded": {
    "triggers": [
      {
        "id": 5814,
        "description": "Send Candidate Status Change Notification",
        "is_required": false,
        "is_default": false,
        "_links": {...}
      },
      {...}
    ]
  }
}

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/5814 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5814,
  "description": "Send Candidate Status Change Notification",
  "is_required": false,
  "is_default": false,
  "_links": {...}
}

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/3203 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3203,
  "filename": "readme.txt",
  "is_resume": true,
  "size": "",
  "version": "",
  "data_item": {
    "id": 5557,
    "type": "candidate"
  }
}

DELETE /attachment/{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/attachment/532 \
-H 'authorization: Token <Your API Key>'
Example Response

GET /attachment/{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/attachment/3203/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": "Santiago",
  "middle_name": "Monserrat",
  "last_name": "Ferry",
  "title": "Customer Accounts Representative",
  "emails": {
    "primary": "Pearlie7@yahoo.com"
  },
  "address": {
    "street": "37438 Alison Manor",
    "city": "East Elenabury",
    "state": "OR",
    "postal_code": "77602-4084"
  },
  "country_code": "US",
  "social_media_urls": [],
  "phones": {
    "home": "(722) 233-7407",
    "cell": "(211) 660-6741",
    "work": "(625) 700-2305"
  },
  "current_employer": "Renner, Lockman and O'Reilly",
  "source": "Google"
}

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/4481 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3460,
  "title": "Forward Operations Liason",
  "candidate_id": 8535,
  "employer": {
    "linked": false,
    "name": "Bashirian - Hilpert",
    "location": {
      "city": "East Audreannefort",
      "state": "NC"
    }
  },
  "supervisor": {
    "linked": false,
    "name": "Iva",
    "phone": "(459) 690-5547"
  },
  "is_verified": true,
  "is_current": "false",
  "start_date": "2016-01-12T11:24:27.227Z",
  "end_date": "2016-12-17T20:07:08.534Z",
  "reason_for_leaving": "Voluptatem iusto autem illo praesentium quae."
}

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/4481 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Corporate Metrics Technician","employer":{"linked":false,"name":"Lehner and Sons","location":{"city":"West Orphamouth","state":"SD"}},"supervisor":{"linked":false,"name":"Lonny","phone":"(615) 778-7292"},"is_verified":true,"is_current":"false","start_date":"2016-08-21T14:05:01.076Z","end_date":"2016-01-08T03:18:03.557Z","reason_for_leaving":"Consequuntur itaque est."}'
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/8532 \
-H 'authorization: Token <Your API Key>'
Example Response

Portals

GET /portals

List all portals

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": 291,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9181,
        "name": "Iusto blanditiis nulla et quas.",
        "date_created": "2016-03-05T19:00:04.910Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /portals/{id}

Get a portal

Parameters
id

required

string

The ID of the portal to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals/9181 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9181,
  "name": "Iusto blanditiis nulla et quas.",
  "date_created": "2016-03-05T19:00:04.910Z",
  "_links": {...},
  "_embedded": {...}
}

GET /portals/{id}/jobs

List jobs

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/9181/jobs \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 625,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 4281,
        "title": "Corporate Metrics Planner",
        "location": {
          "city": "Marilouton",
          "state": "NC",
          "postal_code": "84225-2810"
        },
        "country_code": "US",
        "description": "Voluptatem quasi eligendi voluptatibus architecto quo quo et. In omnis rerum iste assumenda pariatur iusto est autem asperiores. At provident ut ipsam quasi et quia eos quasi ab. Cumque sit molestias. Tempora fuga corporis deserunt deserunt. Et qui tempore consequuntur culpa tempora labore sunt.",
        "notes": "Alias totam aperiam veniam veritatis porro earum.",
        "recruiter_id": 6391,
        "owner_id": 7106,
        "category": null,
        "is_hot": true,
        "start_date": "2016-07-28T17:15:13.130Z",
        "salary": null,
        "max_rate": null,
        "duration": "",
        "external_id": null,
        "company_id": 5854,
        "department_id": 530,
        "status_id": 8455,
        "workflow_id": 7490,
        "date_created": "2016-06-29T16:35:00.774Z",
        "date_modified": "2016-01-19T09:10:44.326Z",
        "_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 band 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 "Careers Portal".

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

Backups

GET /backups

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": 384,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 7722,
        "status": "expired",
        "url": "https://darryl.name",
        "file_size": 294516033,
        "started_by_id": 8339,
        "date_created": "2016-03-14T08:55:42.601Z",
        "_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/2673 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7722,
  "status": "expired",
  "url": "https://darryl.name",
  "file_size": 294516033,
  "started_by_id": 8339,
  "date_created": "2016-03-14T08:55:42.601Z",
  "_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.

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

Tags

GET /tags

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": 429,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 4146,
        "parent_id": 225,
        "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/4146 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4146,
  "parent_id": 225,
  "title": "My Cool Tag Name",
  "_links": {...},
  "_embedded": {...}
}

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

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": 366,
  "_links": {...},
  "_embedded": {
    "webhooks": [
      {
        "id": 1528,
        "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/1528 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 1528,
  "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, candidate.updated, job.updated, contact.updated, company.updated, activity.updated, user.updated, candidate.deleted, job.deleted, contact.deleted, company.deleted, activity.deleted, user.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/8679 \
-H 'authorization: Token <Your API Key>'
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": 7075,
  "mode": "recruiter",
  "subdomain": "kitten",
  "_links": {...},
  "_embedded": {...}
}