CATS API v3

Version 3 of the CATS API is now in public beta. It is a complete redesign and contains many changes from the previous version.

See the version 2 documentation.

This beta version of the API is a preview and is not intended for production use. There are likely to be changes to API behavior that could break any applications that rely on it, so proceed with caution! However, we welcome you to try it out and let us know of any feedback you have.

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

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": 3332,
  "first_name": "Alba",
  "last_name": "Stokes",
  "owner_id": 797,
  ...
  "_links": {
    "self": {
      "href": "/candidates/3332"
    },
    "custom_fields": {
      "href": "/candidates/3332/custom_fields"
    },
    "owner": {
      "href": "/users/797"
    },
    "activities": {
      "href": "/candidates/3332/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": "palma",
      ...
    },
    {...}
  ]
}

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

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>

Changelog

View the changelog for updates and changes to the API.

Activities

GET /activities

List all activities

Parameters
page

required

number

The current page number of activities to return.

per_page

required

number

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": 917,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 5234,
        "data_item": {
          "id": 5132,
          "type": "company"
        },
        "date": "2015-01-16T20:57:26.313Z",
        "regarding_id": 6015,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 7085,
        "date_created": "2015-08-18T02:01:31.979Z",
        "date_modified": "2015-09-10T10:45:16.730Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /activities/{id}

Get an activity

Parameters
id

required

number

The ID of the activity to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/activities/5234 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5234,
  "data_item": {
    "id": 5132,
    "type": "company"
  },
  "date": "2015-01-16T20:57:26.313Z",
  "regarding_id": 6015,
  "type": "call_lvm",
  "notes": "Left voicemail.",
  "annotation": "General",
  "entered_by_id": 7085,
  "date_created": "2015-08-18T02:01:31.979Z",
  "date_modified": "2015-09-10T10:45:16.730Z",
  "_links": {...},
  "_embedded": {...}
}

PUT /activities/{id}

Update an activity

Parameters
id

required

number

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/5025 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":9707,"notes":"Itaque sed ducimus.","date":"2015-06-11T16:47:57.132Z"}'
Example Response

DELETE /activities/{id}

Delete an activity

Parameters
id

required

number

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

number

The current page number of activities to return.

per_page

required

number

The number of activities to return per page.

Example Request
curl -X GET \
'https://api.catsone.com/v3/activities/search?query=Isabell' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 917,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 5234,
        "data_item": {
          "id": 5132,
          "type": "company"
        },
        "date": "2015-01-16T20:57:26.313Z",
        "regarding_id": 6015,
        "type": "call_lvm",
        "notes": "Left voicemail.",
        "annotation": "General",
        "entered_by_id": 7085,
        "date_created": "2015-08-18T02:01:31.979Z",
        "date_modified": "2015-09-10T10:45:16.730Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

Candidates

GET /candidates

List all candidates

Parameters
page

required

number

The current page number of candidates to return.

per_page

required

number

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": 723,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 2936,
        "first_name": "Morris",
        "middle_name": "Ronny",
        "last_name": "Connelly",
        "title": "National Assurance Manager",
        "emails": {
          "primary": "Archibald52@hotmail.com",
          "secondary": "Armando84@gmail.com"
        },
        "address": {
          "street": "3390 Ratke Extensions",
          "city": "Port Florencioview",
          "state": "OH",
          "postal_code": "04390-6547"
        },
        "social_media_urls": [],
        "website": "https://autumn.net",
        "phones": {
          "home": "(906) 836-8682",
          "cell": "(821) 866-3784",
          "work": "(758) 566-9009"
        },
        "best_time_to_call": "After 5pm",
        "current_employer": "Nicolas, Pfannerstill and Sanford",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": true,
        "key_skills": "Programming, management, fishing",
        "notes": "Velit nobis enim.",
        "is_hot": true,
        "contact_id": 6646,
        "owner_id": 3045,
        "entered_by_id": 4322,
        "date_created": "2015-04-01T06:58:14.824Z",
        "date_modified": "2015-09-17T14:08:01.328Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{id}

Get a candidate

Parameters
id

required

number

The ID of the candidate to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/2936 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2936,
  "first_name": "Morris",
  "middle_name": "Ronny",
  "last_name": "Connelly",
  "title": "National Assurance Manager",
  "emails": {
    "primary": "Archibald52@hotmail.com",
    "secondary": "Armando84@gmail.com"
  },
  "address": {
    "street": "3390 Ratke Extensions",
    "city": "Port Florencioview",
    "state": "OH",
    "postal_code": "04390-6547"
  },
  "social_media_urls": [],
  "website": "https://autumn.net",
  "phones": {
    "home": "(906) 836-8682",
    "cell": "(821) 866-3784",
    "work": "(758) 566-9009"
  },
  "best_time_to_call": "After 5pm",
  "current_employer": "Nicolas, Pfannerstill and Sanford",
  "date_available": "Next month",
  "current_pay": "50k",
  "desired_pay": "120k",
  "is_willing_to_relocate": true,
  "key_skills": "Programming, management, fishing",
  "notes": "Velit nobis enim.",
  "is_hot": true,
  "contact_id": 6646,
  "owner_id": 3045,
  "entered_by_id": 4322,
  "date_created": "2015-04-01T06:58:14.824Z",
  "date_modified": "2015-09-17T14:08:01.328Z",
  "_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

boolean

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

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 POST \
'https://api.catsone.com/v3/candidates?check_duplicate=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Reuben","middle_name":"Bailee Bull","last_name":"Kunze","title":"Senior Web Designer","emails":{"primary":"Dawson_Willms85@hotmail.com","secondary":"Olaf.Conroy25@hotmail.com"},"address":{"street":"681 Durgan Isle","city":"Lake Caleshire","state":"Minnesota","postal_code":"63515"},"social_media_urls":[],"website":"","phones":{"home":"(714) 712-8109","cell":"(727) 622-4280","work":"(407) 850-1502"},"best_time_to_call":"","current_employer":"","date_available":"","current_pay":"","desired_pay":"","is_willing_to_relocate":false,"key_skills":"","notes":"","is_active":true,"is_hot":false,"custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

PUT /candidates/{id}

Update a candidate

Parameters
id

required

number

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

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/3844 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Reuben","middle_name":"Bailee Bull","last_name":"Kunze","title":"Senior Web Designer","emails":{"primary":"Dawson_Willms85@hotmail.com","secondary":"Olaf.Conroy25@hotmail.com"},"address":{"street":"681 Durgan Isle","city":"Lake Caleshire","state":"Minnesota","postal_code":"63515"},"social_media_urls":[],"website":"","phones":{"home":"(714) 712-8109","cell":"(727) 622-4280","work":"(407) 850-1502"},"best_time_to_call":"","current_employer":"","date_available":"","current_pay":"","desired_pay":"","is_willing_to_relocate":false,"key_skills":"","notes":"","is_active":true,"is_hot":false,"custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

DELETE /candidates/{id}

Delete a candidate

Parameters
id

required

number

The ID of the candidate to delete.

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

GET /candidates/{id}/pipelines

List pipelines

List all pipelines associated with a candidate.

Parameters
id

required

number

The ID of the candidate to return pipelines for.

page

required

number

The current page number of pipelines to return.

per_page

required

number

The number of pipelines to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/7269/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 254,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 9336,
        "candidate_id": 4259,
        "job_id": 467,
        "rating": 3,
        "status_id": 5324,
        "date_created": "2015-02-13T13:36:27.979Z",
        "date_modified": "2015-04-30T02:18:45.694Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/{id}/tasks

List tasks

Parameters
id

required

number

The ID of the candidate to fetch tasks concerning.

page

required

number

The current page number of tasks to return.

per_page

required

number

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/8868/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 900,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 2465,
        "data_item": {
          "id": 1161,
          "type": "candidate"
        },
        "entered_by_id": 5250,
        "assigned_to_id": 1700,
        "description": "Repellendus quam in sit quis sed sapiente.",
        "priority": 2,
        "date_due": "2015-10-24T16:32:24.962Z",
        "is_completed": true,
        "date_completed": "2015-02-13T05:22:34.570Z",
        "date_created": "2015-01-19T23:10:00.789Z",
        "date_updated": "2015-03-19T02:43:51.015Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/search?query={query}

Search candidates

Parameters
query

required

string

The string to search within candidates for.

page

required

number

The current page number of candidates to return.

per_page

required

number

The number of candidates to return per page.

Example Request
curl -X GET \
'https://api.catsone.com/v3/candidates/search?query=Minerva' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 723,
  "_links": {...},
  "_embedded": {
    "candidates": [
      {
        "id": 2936,
        "first_name": "Morris",
        "middle_name": "Ronny",
        "last_name": "Connelly",
        "title": "National Assurance Manager",
        "emails": {
          "primary": "Archibald52@hotmail.com",
          "secondary": "Armando84@gmail.com"
        },
        "address": {
          "street": "3390 Ratke Extensions",
          "city": "Port Florencioview",
          "state": "OH",
          "postal_code": "04390-6547"
        },
        "social_media_urls": [],
        "website": "https://autumn.net",
        "phones": {
          "home": "(906) 836-8682",
          "cell": "(821) 866-3784",
          "work": "(758) 566-9009"
        },
        "best_time_to_call": "After 5pm",
        "current_employer": "Nicolas, Pfannerstill and Sanford",
        "date_available": "Next month",
        "current_pay": "50k",
        "desired_pay": "120k",
        "is_willing_to_relocate": true,
        "key_skills": "Programming, management, fishing",
        "notes": "Velit nobis enim.",
        "is_hot": true,
        "contact_id": 6646,
        "owner_id": 3045,
        "entered_by_id": 4322,
        "date_created": "2015-04-01T06:58:14.824Z",
        "date_modified": "2015-09-17T14:08:01.328Z",
        "_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

number

The current page number of custom field definitions to return.

per_page

required

number

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": 207,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7899,
        "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

number

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/custom_fields/7899 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7899,
  "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

number

The ID of the candidate to return custom fields for.

page

required

number

The current page number of custom fields to return.

per_page

required

number

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/6388/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "328",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7450,
        "value": "marquise",
        "_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

number

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

custom_field_id

required

number

The ID of the custom field to return.

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

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

Update a custom field

Parameters
candidate_id

required

number

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

custom_field_id

required

number

The ID of the custom field to update.

Body Parameters
value

required

string

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

GET /candidates/{id}/activities

List activities

List all activities associated with a candidate.

Parameters
id

required

number

The ID of the candidate to return activities for.

page

required

number

The current page number of activities to return.

per_page

required

number

The number of activities to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/4548/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 415,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 9663,
        "data_item": {
          "id": 1161,
          "type": "candidate"
        },
        "date_created": "2015-04-21T03:11:57.629Z",
        "regarding_id": 1734,
        "type": "other",
        "notes": "Added candidate to pipeline.",
        "annotation": "General",
        "entered_by_id": 1122,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /candidates/{id}/activities

Create an activity

Log an activity against a candidate.

Parameters
id

required

number

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/9668/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":9707,"notes":"Itaque sed ducimus.","date":"2015-06-11T16:47:57.132Z"}'
Example Response

GET /candidates/{id}/attachments

List attachments

Parameters
id

required

number

The ID of the candidate to return attachments for.

page

required

number

The current page number of attachments to return.

per_page

required

number

The number of attachments to return per page.

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

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

Upload an attachment

Parameters
id

required

number

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/8831/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

number

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/359/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

number

The ID of the candidate to fetch work history for.

page

required

number

The current page number of work history to return.

per_page

required

number

The number of work history items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/4920/work_history \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 342,
  "_links": {...},
  "_embedded": {
    "work_history": [
      {
        "id": 2936,
        "title": "Legacy Identity Developer",
        "candidate_id": 5219,
        "employer": {
          "linked": false,
          "name": "Fritsch - Von",
          "location": {
            "city": "Pabloborough",
            "state": "GA"
          }
        },
        "supervisor": {
          "linked": false,
          "name": "Nyasia",
          "phone": "(302) 548-1272"
        },
        "is_verified": true,
        "is_current": "false",
        "start_date": "2015-03-09T12:25:16.049Z",
        "end_date": "2015-11-02T04:47:23.750Z",
        "reason_for_leaving": "Est nemo aperiam error impedit."
      },
      {...}
    ]
  }
}

GET /candidates/work_history/{id}

Get a work history

Parameters
id

required

number

The ID of the work history to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/work_history/2441 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2936,
  "title": "Legacy Identity Developer",
  "candidate_id": 5219,
  "employer": {
    "linked": false,
    "name": "Fritsch - Von",
    "location": {
      "city": "Pabloborough",
      "state": "GA"
    }
  },
  "supervisor": {
    "linked": false,
    "name": "Nyasia",
    "phone": "(302) 548-1272"
  },
  "is_verified": true,
  "is_current": "false",
  "start_date": "2015-03-09T12:25:16.049Z",
  "end_date": "2015-11-02T04:47:23.750Z",
  "reason_for_leaving": "Est nemo aperiam error impedit."
}

POST /candidates/{id}/work_history

Create a work history

Parameters
id

required

number

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/1541/work_history \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Dynamic Solutions Facilitator","employer":{"linked":false,"name":"Schimmel Group","location":{"city":"South Aubree","state":"GA"}},"supervisor":{"linked":false,"name":"Clyde","phone":"(515) 943-5399"},"is_verified":true,"is_current":"false","start_date":"2015-10-10T12:37:47.923Z","end_date":"2015-02-20T05:16:26.172Z","reason_for_leaving":"Nemo in sit similique sapiente qui dolorem at."}'
Example Response

PUT /candidates/work_history/{id}

Update a work history

Parameters
id

required

number

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/6787 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Dynamic Solutions Facilitator","employer":{"linked":false,"name":"Schimmel Group","location":{"city":"South Aubree","state":"GA"}},"supervisor":{"linked":false,"name":"Clyde","phone":"(515) 943-5399"},"is_verified":true,"is_current":"false","start_date":"2015-10-10T12:37:47.923Z","end_date":"2015-02-20T05:16:26.172Z","reason_for_leaving":"Nemo in sit similique sapiente qui dolorem at."}'
Example Response

DELETE /candidates/work_history/{id}

Delete a work history

Parameters
id

required

number

The ID of the work history to delete.

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

GET /candidates/lists

List all lists

Parameters
page

required

number

The current page number of lists to return.

per_page

required

number

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": 289,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 3537,
        "name": "ipsam",
        "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
        "date_created": "2015-01-13T06:45:31.339Z",
        "date_modified": "2015-06-26T09:15:20.257Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /candidates/lists/{id}

Get a list

Parameters
id

required

number

The ID of the candidate list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists/6309 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3537,
  "name": "ipsam",
  "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
  "date_created": "2015-01-13T06:45:31.339Z",
  "date_modified": "2015-06-26T09:15:20.257Z",
  "_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":"non","notes":"Odit praesentium unde."}'
Example Response

DELETE /candidates/lists/{id}

Delete a list

Parameters
id

required

number

The ID of the candidate list to delete.

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

GET /candidates/lists/{id}/items

List all list items

Parameters
id

required

number

The ID of the candidate list to return items for.

page

required

number

The current page number of list items to return.

per_page

required

number

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists/2234/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 605,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 9501,
        "date_created": "2015-08-04T07:06:38.516Z",
        "candidate_id": 7503,
        "_links": {...},
        "_embedded": {
          "candidate": {
            "id": 2936,
            "first_name": "Morris",
            "middle_name": "Ronny",
            "last_name": "Connelly",
            "title": "National Assurance Manager",
            "emails": {
              "primary": "Archibald52@hotmail.com",
              "secondary": "Armando84@gmail.com"
            },
            "address": {
              "street": "3390 Ratke Extensions",
              "city": "Port Florencioview",
              "state": "OH",
              "postal_code": "04390-6547"
            },
            "social_media_urls": [],
            "website": "https://autumn.net",
            "phones": {
              "home": "(906) 836-8682",
              "cell": "(821) 866-3784",
              "work": "(758) 566-9009"
            },
            "best_time_to_call": "After 5pm",
            "current_employer": "Nicolas, Pfannerstill and Sanford",
            "date_available": "Next month",
            "current_pay": "50k",
            "desired_pay": "120k",
            "is_willing_to_relocate": true,
            "key_skills": "Programming, management, fishing",
            "notes": "Velit nobis enim.",
            "is_hot": true,
            "contact_id": 6646,
            "owner_id": 3045,
            "entered_by_id": 4322,
            "date_created": "2015-04-01T06:58:14.824Z",
            "date_modified": "2015-09-17T14:08:01.328Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a list item

Parameters
list_id

required

number

The ID of the candidate list the item belongs to.

item_id

required

number

The ID of the candidate list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/lists/6263/items/8623 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9501,
  "date_created": "2015-08-04T07:06:38.516Z",
  "candidate_id": 7503,
  "_links": {...},
  "_embedded": {
    "candidate": {
      "id": 2936,
      "first_name": "Morris",
      "middle_name": "Ronny",
      "last_name": "Connelly",
      "title": "National Assurance Manager",
      "emails": {
        "primary": "Archibald52@hotmail.com",
        "secondary": "Armando84@gmail.com"
      },
      "address": {
        "street": "3390 Ratke Extensions",
        "city": "Port Florencioview",
        "state": "OH",
        "postal_code": "04390-6547"
      },
      "social_media_urls": [],
      "website": "https://autumn.net",
      "phones": {
        "home": "(906) 836-8682",
        "cell": "(821) 866-3784",
        "work": "(758) 566-9009"
      },
      "best_time_to_call": "After 5pm",
      "current_employer": "Nicolas, Pfannerstill and Sanford",
      "date_available": "Next month",
      "current_pay": "50k",
      "desired_pay": "120k",
      "is_willing_to_relocate": true,
      "key_skills": "Programming, management, fishing",
      "notes": "Velit nobis enim.",
      "is_hot": true,
      "contact_id": 6646,
      "owner_id": 3045,
      "entered_by_id": 4322,
      "date_created": "2015-04-01T06:58:14.824Z",
      "date_modified": "2015-09-17T14:08:01.328Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /candidates/lists/{id}/items

Create a list item

Creating a candidate list item attaches the specified candidate to a list.

Parameters
id

required

number

The ID of the candidate list.

Body Parameters
candidate_id

required

number

Example Request
curl -X POST \
https://api.catsone.com/v3/candidates/lists/1042/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"candidate_id":8969}'
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

number

The ID of the candidate list.

item_id

required

number

The ID of the list item to delete.

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

GET /candidates/{candidate_id}/applications

List all applications

Parameters
candidate_id

required

number

The ID of the candidate to return applications for.

page

required

number

The current page number of list items to return.

per_page

required

number

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/5557/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 438,
  "_links": {...},
  "_embedded": {
    "applications": [
      {
        "id": 7046,
        "job_id": "5251",
        "date_created": "2015-05-22T01:07:38.857Z",
        "_links": {...},
        "_embedded": {
          "fields": []
        }
      },
      {...}
    ]
  }
}

GET /candidates/applications/{application_id}

Get an application

Parameters
application_id

required

number

The ID of the applications to return.

page

required

number

The current page number of list items to return.

per_page

required

number

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/applications/3401 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7046,
  "job_id": "5251",
  "date_created": "2015-05-22T01:07:38.857Z",
  "_links": {...},
  "_embedded": {
    "fields": []
  }
}

GET /candidates/{candidate_id}/tags

List all tags

Parameters
candidate_id

required

number

The ID of the candidate to return tags for.

page

required

number

The current page number of tags to return.

per_page

required

number

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/candidates/9002/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 575,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 2307,
        "parent_id": 1931,
        "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

number

The ID of the candidate to replace tags on.

Body Parameters
tags

array

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

PUT /candidates/{candidate_id}/tags

Attach Tags

This will not delete any existing tags on the candidate.

Parameters
candidate_id

required

number

The ID of the candidate to attach tags to.

Body Parameters
tags

array

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

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

Delete Tag

Detaches an individual tag from the candidate.

Parameters
candidate_id

required

number

The ID of the candidate to detach the tag from.

tag_id

required

number

The ID of the tag to detach.

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

Contacts

GET /contacts

List all contacts

Parameters
page

required

number

The current page number of contacts to return.

per_page

required

number

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": 548,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 4597,
        "first_name": "Marlene",
        "last_name": "Hagenes",
        "title": "Internal Infrastructure Executive",
        "reports_to_id": 1184,
        "emails": {
          "primary": "Lenny_Hayes@yahoo.com",
          "secondary": "Linnie_Wehner20@yahoo.com"
        },
        "phones": {
          "cell": "(929) 624-5015",
          "work": "(958) 344-7158",
          "other": "(277) 471-1273"
        },
        "address": {
          "street": "3390 Ratke Extensions",
          "city": "Port Florencioview",
          "state": "OH",
          "postal_code": "04390-6547"
        },
        "social_media_urls": [],
        "is_hot": true,
        "notes": "Et deleniti voluptas ex magni.",
        "entered_by_id": 4461,
        "status_id": 6400,
        "date_created": "2015-08-17T05:56:27.308Z",
        "date_modified": "2015-05-12T21:25:39.611Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/{id}

Get a contact

Parameters
id

required

number

The ID of the contact to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/4597 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4597,
  "first_name": "Marlene",
  "last_name": "Hagenes",
  "title": "Internal Infrastructure Executive",
  "reports_to_id": 1184,
  "emails": {
    "primary": "Lenny_Hayes@yahoo.com",
    "secondary": "Linnie_Wehner20@yahoo.com"
  },
  "phones": {
    "cell": "(929) 624-5015",
    "work": "(958) 344-7158",
    "other": "(277) 471-1273"
  },
  "address": {
    "street": "3390 Ratke Extensions",
    "city": "Port Florencioview",
    "state": "OH",
    "postal_code": "04390-6547"
  },
  "social_media_urls": [],
  "is_hot": true,
  "notes": "Et deleniti voluptas ex magni.",
  "entered_by_id": 4461,
  "status_id": 6400,
  "date_created": "2015-08-17T05:56:27.308Z",
  "date_modified": "2015-05-12T21:25:39.611Z",
  "_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

boolean

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>"
}
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":"Jeremy","last_name":"Emmerich","owner_id":9545,"company_id":4157,"title":"Chief Optimization Specialist","reports_to_id":1839,"emails":{"primary":"Evelyn_Fay37@yahoo.com","secondary":"Elise75@gmail.com"},"phones":{"work":"(854) 306-2207","cell":"(513) 984-2483","other":"(537) 890-5300"},"has_left_company":false,"address":{"street":"6638 Gutmann Mountains","city":"South Katlynn","state":"Ohio","postal_code":"75698"},"social_media_urls":[],"is_hot":false,"notes":"Laboriosam alias amet aperiam laboriosam consequatur possimus et.","custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

PUT /contacts/{id}

Update a contact

Parameters
id

required

number

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>"
}
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/6871 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"first_name":"Jeremy","last_name":"Emmerich","owner_id":9545,"company_id":4157,"title":"Chief Optimization Specialist","reports_to_id":1839,"emails":{"primary":"Evelyn_Fay37@yahoo.com","secondary":"Elise75@gmail.com"},"phones":{"work":"(854) 306-2207","cell":"(513) 984-2483","other":"(537) 890-5300"},"has_left_company":false,"address":{"street":"6638 Gutmann Mountains","city":"South Katlynn","state":"Ohio","postal_code":"75698"},"social_media_urls":[],"is_hot":false,"notes":"Laboriosam alias amet aperiam laboriosam consequatur possimus et.","custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

DELETE /contacts/{id}

Delete a contact

Parameters
id

required

number

The ID of the contact to delete.

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

GET /contacts/{id}/tasks

List tasks

Parameters
id

required

number

The ID of the contact to fetch tasks concerning.

page

required

number

The current page number of tasks to return.

per_page

required

number

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/3145/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 902,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 2465,
        "data_item": {
          "id": 1306,
          "type": "contact"
        },
        "entered_by_id": 5197,
        "assigned_to_id": 7382,
        "description": "Et voluptate qui.",
        "priority": 2,
        "date_due": "2015-12-25T22:10:20.158Z",
        "is_completed": true,
        "date_completed": "2015-02-22T00:57:06.035Z",
        "date_created": "2015-02-08T01:45:51.957Z",
        "date_updated": "2015-03-24T16:32:52.659Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/search?query={query}

Search contacts

Parameters
query

required

string

The string to search within contacts for.

page

required

number

The current page number of contacts to return.

per_page

required

number

The number of contacts to return per page.

Example Request
curl -X GET \
'https://api.catsone.com/v3/contacts/search?query=Werner' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 548,
  "_links": {...},
  "_embedded": {
    "contacts": [
      {
        "id": 4597,
        "first_name": "Marlene",
        "last_name": "Hagenes",
        "title": "Internal Infrastructure Executive",
        "reports_to_id": 1184,
        "emails": {
          "primary": "Lenny_Hayes@yahoo.com",
          "secondary": "Linnie_Wehner20@yahoo.com"
        },
        "phones": {
          "cell": "(929) 624-5015",
          "work": "(958) 344-7158",
          "other": "(277) 471-1273"
        },
        "address": {
          "street": "3390 Ratke Extensions",
          "city": "Port Florencioview",
          "state": "OH",
          "postal_code": "04390-6547"
        },
        "social_media_urls": [],
        "is_hot": true,
        "notes": "Et deleniti voluptas ex magni.",
        "entered_by_id": 4461,
        "status_id": 6400,
        "date_created": "2015-08-17T05:56:27.308Z",
        "date_modified": "2015-05-12T21:25:39.611Z",
        "_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

number

The current page number of custom field definitions to return.

per_page

required

number

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": 716,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7899,
        "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

number

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/custom_fields/7899 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7899,
  "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

number

The ID of the contact to return custom fields for.

page

required

number

The current page number of custom fields to return.

per_page

required

number

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/1251/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "328",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7450,
        "value": "marquise",
        "_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

number

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

custom_field_id

required

number

The ID of the custom field to return.

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

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

Update a custom field

Parameters
contact_id

required

number

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

custom_field_id

required

number

The ID of the custom field to update.

Body Parameters
value

required

string

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

GET /contacts/{id}/activities

List activities

List all activities associated with a contact.

Parameters
id

required

number

The ID of the contact to return activities for.

page

required

number

The current page number of activities to return.

per_page

required

number

The number of activities to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/8546/activities \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 563,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 6481,
        "data_item": {
          "id": 1306,
          "type": "contact"
        },
        "date_created": "2015-09-12T12:08:28.202Z",
        "regarding_id": 8739,
        "type": "type_other",
        "notes": "Added candidate to pipeline.",
        "annotation": "General",
        "entered_by_id": 1070,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

POST /contacts/{id}/activities

Create an activity

Log an activity against a contact.

Parameters
id

required

number

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/7697/activities \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"type":"call_lvm","regarding_id":9707,"notes":"Itaque sed ducimus.","date":"2015-06-11T16:47:57.132Z"}'
Example Response

GET /contacts/statuses

List statuses

Parameters
page

required

number

The current page number of statuses to return.

per_page

required

number

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": 205,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 3286,
        "title": "Employee",
        "mapping": "human_resources",
        "prerequisites": [
          {
            "id": 9676
          }
        ],
        "triggers": [
          {
            "id": 9338
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /contacts/statuses/{id}

Get a status

Parameters
id

required

number

The ID of the status to return.

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

POST /contacts/{id}/status

Change status

Parameters
id

required

number

The ID of the contact 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/contacts/6976/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":1624,"triggers":[{"id":1996,"fire":true}]}'
Example Response

GET /contacts/{id}/attachments

List attachments

Parameters
id

required

number

The ID of the contact to return attachments for.

page

required

number

The current page number of attachments to return.

per_page

required

number

The number of attachments to return per page.

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

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

Upload an attachment

Parameters
id

required

number

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/9224/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

number

The current page number of lists to return.

per_page

required

number

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": 289,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 3537,
        "name": "ipsam",
        "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
        "date_created": "2015-01-13T06:45:31.339Z",
        "date_modified": "2015-06-26T09:15:20.257Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /contacts/lists/{id}

Get a list

Parameters
id

required

number

The ID of the contact list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists/1872 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3537,
  "name": "ipsam",
  "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
  "date_created": "2015-01-13T06:45:31.339Z",
  "date_modified": "2015-06-26T09:15:20.257Z",
  "_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":"non","notes":"Odit praesentium unde."}'
Example Response

DELETE /contacts/lists/{id}

Delete a list

Parameters
id

required

number

The ID of the contact list to delete.

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

GET /contacts/lists/{id}/items

List all list items

Parameters
id

required

number

The ID of the contact list to return items for.

page

required

number

The current page number of list items to return.

per_page

required

number

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists/9917/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 494,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 2958,
        "date_created": "2015-12-01T03:18:17.299Z",
        "contact_id": 688,
        "_links": {...},
        "_embedded": {
          "contact": {
            "id": 4597,
            "first_name": "Marlene",
            "last_name": "Hagenes",
            "title": "Internal Infrastructure Executive",
            "reports_to_id": 1184,
            "emails": {
              "primary": "Lenny_Hayes@yahoo.com",
              "secondary": "Linnie_Wehner20@yahoo.com"
            },
            "phones": {
              "cell": "(929) 624-5015",
              "work": "(958) 344-7158",
              "other": "(277) 471-1273"
            },
            "address": {
              "street": "3390 Ratke Extensions",
              "city": "Port Florencioview",
              "state": "OH",
              "postal_code": "04390-6547"
            },
            "social_media_urls": [],
            "is_hot": true,
            "notes": "Et deleniti voluptas ex magni.",
            "entered_by_id": 4461,
            "status_id": 6400,
            "date_created": "2015-08-17T05:56:27.308Z",
            "date_modified": "2015-05-12T21:25:39.611Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a list item

Parameters
list_id

required

number

The ID of the contact list the item belongs to.

item_id

required

number

The ID of the contact list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/lists/6755/items/9422 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2958,
  "date_created": "2015-12-01T03:18:17.299Z",
  "contact_id": 688,
  "_links": {...},
  "_embedded": {
    "contact": {
      "id": 4597,
      "first_name": "Marlene",
      "last_name": "Hagenes",
      "title": "Internal Infrastructure Executive",
      "reports_to_id": 1184,
      "emails": {
        "primary": "Lenny_Hayes@yahoo.com",
        "secondary": "Linnie_Wehner20@yahoo.com"
      },
      "phones": {
        "cell": "(929) 624-5015",
        "work": "(958) 344-7158",
        "other": "(277) 471-1273"
      },
      "address": {
        "street": "3390 Ratke Extensions",
        "city": "Port Florencioview",
        "state": "OH",
        "postal_code": "04390-6547"
      },
      "social_media_urls": [],
      "is_hot": true,
      "notes": "Et deleniti voluptas ex magni.",
      "entered_by_id": 4461,
      "status_id": 6400,
      "date_created": "2015-08-17T05:56:27.308Z",
      "date_modified": "2015-05-12T21:25:39.611Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /contacts/lists/{id}/items

Create a list item

Creating a contact list item attaches the specified contact to a list.

Parameters
id

required

number

The ID of the contact list.

Body Parameters
contact_id

required

number

Example Request
curl -X POST \
https://api.catsone.com/v3/contacts/lists/9680/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"contact_id":1852}'
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

number

The ID of the contact list.

item_id

required

number

The ID of the list item to delete.

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

GET /contacts/{contact_id}/tags

List all tags

Parameters
contact_id

required

number

The ID of the contact to return tags for.

page

required

number

The current page number of tags to return.

per_page

required

number

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/contacts/9658/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 575,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 2307,
        "parent_id": 1931,
        "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

number

The ID of the contact to replace tags on.

Body Parameters
tags

array

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

PUT /contacts/{contact_id}/tags

Attach Tags

This will not delete any existing tags on the contact.

Parameters
contact_id

required

number

The ID of the contact to attach tags to.

Body Parameters
tags

array

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

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

Delete Tag

Detaches an individual tag from the contact.

Parameters
contact_id

required

number

The ID of the contact to detach the tag from.

tag_id

required

number

The ID of the tag to detach.

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

Companies

GET /companies

List all companies

Parameters
page

required

number

The current page number of companies to return.

per_page

required

number

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": 772,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 957,
        "owner_id": 7577,
        "name": "Pfannerstill, Kunze and Brakus",
        "website": "http://kelsie.info",
        "address": {
          "street": "3390 Ratke Extensions",
          "city": "Port Florencioview",
          "state": "OH",
          "postal_code": "04390-6547"
        },
        "phones": {
          "primary": "(650) 765-1607",
          "secondary": "(251) 398-4746",
          "fax": "(605) 499-1914"
        },
        "departments": [],
        "entered_by": "Javonte Pollich",
        "social_media_urls": [],
        "notes": "Ut aut natus ut eligendi dolorem id nihil qui dolorum.",
        "is_hot": true,
        "key_technologies": "",
        "billing_contact_id": 3194,
        "status_id": 6835,
        "date_created": "2015-06-03T04:16:30.818Z",
        "date_modified": "2015-07-22T05:46:46.413Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/{id}

Get a company

Parameters
id

required

number

The ID of the company to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/957 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 957,
  "owner_id": 7577,
  "name": "Pfannerstill, Kunze and Brakus",
  "website": "http://kelsie.info",
  "address": {
    "street": "3390 Ratke Extensions",
    "city": "Port Florencioview",
    "state": "OH",
    "postal_code": "04390-6547"
  },
  "phones": {
    "primary": "(650) 765-1607",
    "secondary": "(251) 398-4746",
    "fax": "(605) 499-1914"
  },
  "departments": [],
  "entered_by": "Javonte Pollich",
  "social_media_urls": [],
  "notes": "Ut aut natus ut eligendi dolorem id nihil qui dolorum.",
  "is_hot": true,
  "key_technologies": "",
  "billing_contact_id": 3194,
  "status_id": 6835,
  "date_created": "2015-06-03T04:16:30.818Z",
  "date_modified": "2015-07-22T05:46:46.413Z",
  "_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

boolean

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

array

entered_by

string

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":"Hansen Inc","owner_id":4749,"website":"http://junius.name","address":{"street":"63576 Smitham Roads","city":"Port Donato","state":"Nevada","postal_code":"90870"},"phones":{"primary":"(704) 781-4635","secondary":"(569) 893-6074","fax":"(242) 959-3992"},"departments":[],"entered_by":"Uriel Parker","social_media_urls":[],"notes":"Odit est ut dolor sint molestiae ut minima.","is_hot":true,"key_technologies":"","billing_contact_id":9874,"custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

PUT /companies/{id}

Update a company

Parameters
id

required

number

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

array

entered_by

string

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/3171 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"name":"Hansen Inc","owner_id":4749,"website":"http://junius.name","address":{"street":"63576 Smitham Roads","city":"Port Donato","state":"Nevada","postal_code":"90870"},"phones":{"primary":"(704) 781-4635","secondary":"(569) 893-6074","fax":"(242) 959-3992"},"departments":[],"entered_by":"Uriel Parker","social_media_urls":[],"notes":"Odit est ut dolor sint molestiae ut minima.","is_hot":true,"key_technologies":"","billing_contact_id":9874,"custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

DELETE /companies/{id}

Delete a company

Parameters
id

required

number

The ID of the company to delete.

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

GET /companies/{id}/tasks

List tasks

Parameters
id

required

number

The ID of the company to fetch tasks concerning.

page

required

number

The current page number of tasks to return.

per_page

required

number

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/5977/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 744,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 2465,
        "data_item": {
          "id": 6675,
          "type": "company"
        },
        "entered_by_id": 6077,
        "assigned_to_id": 4507,
        "description": "Vel illo laboriosam laboriosam nisi illo.",
        "priority": 2,
        "date_due": "2015-12-25T16:36:35.260Z",
        "is_completed": true,
        "date_completed": "2015-05-06T23:03:12.028Z",
        "date_created": "2015-09-16T05:47:22.343Z",
        "date_updated": "2015-08-26T21:15:06.121Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/search?query={query}

Search companies

Parameters
query

required

string

The string to search within companies for.

page

required

number

The current page number of companies to return.

per_page

required

number

The number of companies to return per page.

Example Request
curl -X GET \
'https://api.catsone.com/v3/companies/search?query=Isobel' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 772,
  "_links": {...},
  "_embedded": {
    "companies": [
      {
        "id": 957,
        "owner_id": 7577,
        "name": "Pfannerstill, Kunze and Brakus",
        "website": "http://kelsie.info",
        "address": {
          "street": "3390 Ratke Extensions",
          "city": "Port Florencioview",
          "state": "OH",
          "postal_code": "04390-6547"
        },
        "phones": {
          "primary": "(650) 765-1607",
          "secondary": "(251) 398-4746",
          "fax": "(605) 499-1914"
        },
        "departments": [],
        "entered_by": "Javonte Pollich",
        "social_media_urls": [],
        "notes": "Ut aut natus ut eligendi dolorem id nihil qui dolorum.",
        "is_hot": true,
        "key_technologies": "",
        "billing_contact_id": 3194,
        "status_id": 6835,
        "date_created": "2015-06-03T04:16:30.818Z",
        "date_modified": "2015-07-22T05:46:46.413Z",
        "_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

number

The current page number of custom field definitions to return.

per_page

required

number

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": 728,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7899,
        "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

number

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/custom_fields/7899 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7899,
  "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

number

The ID of the company to return custom fields for.

page

required

number

The current page number of custom fields to return.

per_page

required

number

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/3146/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "328",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7450,
        "value": "marquise",
        "_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

number

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

custom_field_id

required

number

The ID of the custom field to return.

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

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

Update a custom field

Parameters
company_id

required

number

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

custom_field_id

required

number

The ID of the custom field to update.

Body Parameters
value

required

string

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

GET /companies/statuses

List statuses

Parameters
page

required

number

The current page number of statuses to return.

per_page

required

number

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": 596,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 3286,
        "title": "Lead",
        "mapping": "lead",
        "prerequisites": [
          {
            "id": 9676
          }
        ],
        "triggers": [
          {
            "id": 9338
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /companies/statuses/{id}

Get a status

Parameters
id

required

number

The ID of the status to return.

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

POST /companies/{id}/status

Change status

Parameters
id

required

number

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

GET /companies/{id}/attachments

List attachments

Parameters
id

required

number

The ID of the company to return attachments for.

page

required

number

The current page number of attachments to return.

per_page

required

number

The number of attachments to return per page.

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

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

Upload an attachment

Parameters
id

required

number

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/8096/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

number

The current page number of lists to return.

per_page

required

number

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": 289,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 3537,
        "name": "ipsam",
        "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
        "date_created": "2015-01-13T06:45:31.339Z",
        "date_modified": "2015-06-26T09:15:20.257Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /companies/lists/{id}

Get a list

Parameters
id

required

number

The ID of the company list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists/5627 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3537,
  "name": "ipsam",
  "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
  "date_created": "2015-01-13T06:45:31.339Z",
  "date_modified": "2015-06-26T09:15:20.257Z",
  "_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":"non","notes":"Odit praesentium unde."}'
Example Response

DELETE /companies/lists/{id}

Delete a list

Parameters
id

required

number

The ID of the company list to delete.

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

GET /companies/lists/{id}/items

List all list items

Parameters
id

required

number

The ID of the company list to return items for.

page

required

number

The current page number of list items to return.

per_page

required

number

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists/2281/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 588,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 3762,
        "date_created": "2015-05-10T06:15:21.873Z",
        "company_id": 427,
        "_links": {...},
        "_embedded": {
          "company": {
            "id": 957,
            "owner_id": 7577,
            "name": "Pfannerstill, Kunze and Brakus",
            "website": "http://kelsie.info",
            "address": {
              "street": "3390 Ratke Extensions",
              "city": "Port Florencioview",
              "state": "OH",
              "postal_code": "04390-6547"
            },
            "phones": {
              "primary": "(650) 765-1607",
              "secondary": "(251) 398-4746",
              "fax": "(605) 499-1914"
            },
            "departments": [],
            "entered_by": "Javonte Pollich",
            "social_media_urls": [],
            "notes": "Ut aut natus ut eligendi dolorem id nihil qui dolorum.",
            "is_hot": true,
            "key_technologies": "",
            "billing_contact_id": 3194,
            "status_id": 6835,
            "date_created": "2015-06-03T04:16:30.818Z",
            "date_modified": "2015-07-22T05:46:46.413Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a list item

Parameters
list_id

required

number

The ID of the company list the item belongs to.

item_id

required

number

The ID of the company list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/lists/6068/items/7558 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3762,
  "date_created": "2015-05-10T06:15:21.873Z",
  "company_id": 427,
  "_links": {...},
  "_embedded": {
    "company": {
      "id": 957,
      "owner_id": 7577,
      "name": "Pfannerstill, Kunze and Brakus",
      "website": "http://kelsie.info",
      "address": {
        "street": "3390 Ratke Extensions",
        "city": "Port Florencioview",
        "state": "OH",
        "postal_code": "04390-6547"
      },
      "phones": {
        "primary": "(650) 765-1607",
        "secondary": "(251) 398-4746",
        "fax": "(605) 499-1914"
      },
      "departments": [],
      "entered_by": "Javonte Pollich",
      "social_media_urls": [],
      "notes": "Ut aut natus ut eligendi dolorem id nihil qui dolorum.",
      "is_hot": true,
      "key_technologies": "",
      "billing_contact_id": 3194,
      "status_id": 6835,
      "date_created": "2015-06-03T04:16:30.818Z",
      "date_modified": "2015-07-22T05:46:46.413Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /companies/lists/{id}/items

Create a list item

Creating a company list item attaches the specified company to a list.

Parameters
id

required

number

The ID of the company list.

Body Parameters
company_id

required

number

Example Request
curl -X POST \
https://api.catsone.com/v3/companies/lists/9692/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"company_id":6196}'
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

number

The ID of the company list.

item_id

required

number

The ID of the list item to delete.

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

GET /companies/{company_id}/tags

List all tags

Parameters
company_id

required

number

The ID of the company to return tags for.

page

required

number

The current page number of tags to return.

per_page

required

number

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/companies/4672/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 575,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 2307,
        "parent_id": 1931,
        "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

number

The ID of the company to replace tags on.

Body Parameters
tags

array

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

PUT /companies/{company_id}/tags

Attach Tags

This will not delete any existing tags on the company.

Parameters
company_id

required

number

The ID of the company to attach tags to.

Body Parameters
tags

array

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

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

Delete Tag

Detaches an individual tag from the company.

Parameters
company_id

required

number

The ID of the company to detach the tag from.

tag_id

required

number

The ID of the tag to detach.

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

Jobs

GET /jobs

List all jobs

Parameters
page

required

number

The current page number of jobs to return.

per_page

required

number

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": 233,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6191,
        "title": "Product Response Representative",
        "location": {
          "city": "Kihntown",
          "state": "MS",
          "postal_code": "73803-2006"
        },
        "description": "Ullam repellat consectetur neque dolores ut dolore. Et minus aperiam omnis commodi minus expedita quaerat aut voluptate. Distinctio consequatur repellat tempora sed. Veniam eos id minima.",
        "notes": "Neque alias dolorem praesentium rem.",
        "recruiter_id": 2079,
        "owner_id": 6542,
        "category": null,
        "is_hot": false,
        "start_date": "2015-10-29T02:52:36.494Z",
        "salary": null,
        "duration": "",
        "external_id": null,
        "company_id": 3033,
        "status_id": 6645,
        "date_created": "2015-03-15T07:36:03.774Z",
        "date_modified": "2015-07-03T20:02:49.195Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{id}

Get a job

Parameters
id

required

number

The ID of the job to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/6191 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6191,
  "title": "Product Response Representative",
  "location": {
    "city": "Kihntown",
    "state": "MS",
    "postal_code": "73803-2006"
  },
  "description": "Ullam repellat consectetur neque dolores ut dolore. Et minus aperiam omnis commodi minus expedita quaerat aut voluptate. Distinctio consequatur repellat tempora sed. Veniam eos id minima.",
  "notes": "Neque alias dolorem praesentium rem.",
  "recruiter_id": 2079,
  "owner_id": 6542,
  "category": null,
  "is_hot": false,
  "start_date": "2015-10-29T02:52:36.494Z",
  "salary": null,
  "duration": "",
  "external_id": null,
  "company_id": 3033,
  "status_id": 6645,
  "date_created": "2015-03-15T07:36:03.774Z",
  "date_modified": "2015-07-03T20:02:49.195Z",
  "_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

boolean

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

required

number

The ID of the company the job belongs to.

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

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 POST \
'https://api.catsone.com/v3/jobs?check_duplicate=true' \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Principal Security Developer","location":{"city":"Robelstad","state":"DE","postal_code":"89001"},"company_id":4223,"recruiter_id":5199,"category_name":"","is_hot":true,"start_date":"2015-01-05T13:06:33.482Z","salary":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":6943,"custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

PUT /jobs/{id}

Update a job

Parameters
id

required

number

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

required

number

The ID of the company the job belongs to.

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

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/2750 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Principal Security Developer","location":{"city":"Robelstad","state":"DE","postal_code":"89001"},"company_id":4223,"recruiter_id":5199,"category_name":"","is_hot":true,"start_date":"2015-01-05T13:06:33.482Z","salary":"","duration":"","type":"","openings":0,"external_id":"","description":"","notes":"","contact_id":6943,"custom_fields":[{"id":1776,"value":"lorem"}]}'
Example Response

DELETE /jobs/{id}

Delete a job

Parameters
id

required

number

The ID of the job to delete.

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

GET /jobs/{id}/pipelines

List pipelines

List all pipelines associated with a job.

Parameters
id

required

number

The ID of the job to return pipelines for.

page

required

number

The current page number of pipelines to return.

per_page

required

number

The number of pipelines to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/7795/pipelines \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 254,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 9336,
        "candidate_id": 4259,
        "job_id": 467,
        "rating": 3,
        "status_id": 5324,
        "date_created": "2015-02-13T13:36:27.979Z",
        "date_modified": "2015-04-30T02:18:45.694Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{job_id}/applications

List applications

Parameters
page

required

number

The current page number of contacts to return.

per_page

required

number

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": 238,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 7046,
        "description": "Porro distinctio assumenda minima.",
        "header": "Expedita voluptates corporis alias dolores voluptates iusto.",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{id}/tasks

List tasks

Parameters
id

required

number

The ID of the job to fetch tasks concerning.

page

required

number

The current page number of tasks to return.

per_page

required

number

The number of task items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/5018/tasks \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 413,
  "_links": {...},
  "_embedded": {
    "tasks": [
      {
        "id": 2465,
        "data_item": {
          "id": 5909,
          "type": "job"
        },
        "entered_by_id": 9714,
        "assigned_to_id": 9359,
        "description": "Voluptas ducimus ab ipsa vero et.",
        "priority": 2,
        "date_due": "2015-10-04T04:44:52.056Z",
        "is_completed": true,
        "date_completed": "2015-05-04T10:26:42.920Z",
        "date_created": "2015-07-18T18:27:22.468Z",
        "date_updated": "2015-02-08T21:48:06.293Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/search?query={query}

Search jobs

Parameters
query

required

string

The string to search within jobs for.

page

required

number

The current page number of jobs to return.

per_page

required

number

The number of jobs to return per page.

Example Request
curl -X GET \
'https://api.catsone.com/v3/jobs/search?query=Mckenna' \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 233,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6191,
        "title": "Product Response Representative",
        "location": {
          "city": "Kihntown",
          "state": "MS",
          "postal_code": "73803-2006"
        },
        "description": "Ullam repellat consectetur neque dolores ut dolore. Et minus aperiam omnis commodi minus expedita quaerat aut voluptate. Distinctio consequatur repellat tempora sed. Veniam eos id minima.",
        "notes": "Neque alias dolorem praesentium rem.",
        "recruiter_id": 2079,
        "owner_id": 6542,
        "category": null,
        "is_hot": false,
        "start_date": "2015-10-29T02:52:36.494Z",
        "salary": null,
        "duration": "",
        "external_id": null,
        "company_id": 3033,
        "status_id": 6645,
        "date_created": "2015-03-15T07:36:03.774Z",
        "date_modified": "2015-07-03T20:02:49.195Z",
        "_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

number

The current page number of custom field definitions to return.

per_page

required

number

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": 842,
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7899,
        "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

number

The ID of the custom field definition to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/custom_fields/7899 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7899,
  "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

number

The ID of the job to return custom fields for.

page

required

number

The current page number of custom fields to return.

per_page

required

number

The number of custom fields to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/8885/custom_fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": "328",
  "_links": {...},
  "_embedded": {
    "custom_fields": [
      {
        "id": 7450,
        "value": "marquise",
        "_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

number

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

custom_field_id

required

number

The ID of the custom field to return.

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

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

Update a custom field

Parameters
job_id

required

number

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

custom_field_id

required

number

The ID of the custom field to update.

Body Parameters
value

required

string

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

GET /jobs/statuses

List statuses

Parameters
page

required

number

The current page number of statuses to return.

per_page

required

number

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": 965,
  "_links": {...},
  "_embedded": {
    "statuses": [
      {
        "id": 3286,
        "title": "Active",
        "mapping": 0,
        "prerequisites": [
          {
            "id": 9676
          }
        ],
        "triggers": [
          {
            "id": 9338
          }
        ],
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /jobs/statuses/{id}

Get a status

Parameters
id

required

number

The ID of the status to return.

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

POST /jobs/{id}/status

Change status

Parameters
id

required

number

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

GET /jobs/{id}/attachments

List attachments

Parameters
id

required

number

The ID of the candidate to return attachments for.

page

required

number

The current page number of attachments to return.

per_page

required

number

The number of attachments to return per page.

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

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

Upload an attachment

Parameters
id

required

number

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/4698/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

number

The current page number of lists to return.

per_page

required

number

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": 289,
  "_links": {...},
  "_embedded": {
    "lists": [
      {
        "id": 3537,
        "name": "ipsam",
        "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
        "date_created": "2015-01-13T06:45:31.339Z",
        "date_modified": "2015-06-26T09:15:20.257Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/lists/{id}

Get a list

Parameters
id

required

number

The ID of the job list to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists/2694 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 3537,
  "name": "ipsam",
  "notes": "Non enim voluptatibus aperiam neque fugit temporibus voluptatem dolorum quasi.",
  "date_created": "2015-01-13T06:45:31.339Z",
  "date_modified": "2015-06-26T09:15:20.257Z",
  "_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":"non","notes":"Odit praesentium unde."}'
Example Response

DELETE /jobs/lists/{id}

Delete a list

Parameters
id

required

number

The ID of the job list to delete.

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

GET /jobs/lists/{id}/items

List all list items

Parameters
id

required

number

The ID of the job list to return items for.

page

required

number

The current page number of list items to return.

per_page

required

number

The number of list items to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists/7499/items \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 973,
  "_links": {...},
  "_embedded": {
    "items": [
      {
        "id": 2180,
        "date_created": "2015-02-26T07:28:54.422Z",
        "job_id": 8625,
        "_links": {...},
        "_embedded": {
          "job": {
            "id": 6191,
            "title": "Product Response Representative",
            "location": {
              "city": "Kihntown",
              "state": "MS",
              "postal_code": "73803-2006"
            },
            "description": "Ullam repellat consectetur neque dolores ut dolore. Et minus aperiam omnis commodi minus expedita quaerat aut voluptate. Distinctio consequatur repellat tempora sed. Veniam eos id minima.",
            "notes": "Neque alias dolorem praesentium rem.",
            "recruiter_id": 2079,
            "owner_id": 6542,
            "category": null,
            "is_hot": false,
            "start_date": "2015-10-29T02:52:36.494Z",
            "salary": null,
            "duration": "",
            "external_id": null,
            "company_id": 3033,
            "status_id": 6645,
            "date_created": "2015-03-15T07:36:03.774Z",
            "date_modified": "2015-07-03T20:02:49.195Z",
            "_links": {...},
            "_embedded": {...}
          }
        }
      },
      {...}
    ]
  }
}

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

Get a list item

Parameters
list_id

required

number

The ID of the job list the item belongs to.

item_id

required

number

The ID of the job list item to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/lists/9781/items/485 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2180,
  "date_created": "2015-02-26T07:28:54.422Z",
  "job_id": 8625,
  "_links": {...},
  "_embedded": {
    "job": {
      "id": 6191,
      "title": "Product Response Representative",
      "location": {
        "city": "Kihntown",
        "state": "MS",
        "postal_code": "73803-2006"
      },
      "description": "Ullam repellat consectetur neque dolores ut dolore. Et minus aperiam omnis commodi minus expedita quaerat aut voluptate. Distinctio consequatur repellat tempora sed. Veniam eos id minima.",
      "notes": "Neque alias dolorem praesentium rem.",
      "recruiter_id": 2079,
      "owner_id": 6542,
      "category": null,
      "is_hot": false,
      "start_date": "2015-10-29T02:52:36.494Z",
      "salary": null,
      "duration": "",
      "external_id": null,
      "company_id": 3033,
      "status_id": 6645,
      "date_created": "2015-03-15T07:36:03.774Z",
      "date_modified": "2015-07-03T20:02:49.195Z",
      "_links": {...},
      "_embedded": {...}
    }
  }
}

POST /jobs/lists/{id}/items

Create a list item

Creating a job list item attaches the specified job to a list.

Parameters
id

required

number

The ID of the job list.

Body Parameters
job_id

required

number

Example Request
curl -X POST \
https://api.catsone.com/v3/jobs/lists/4508/items \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"job_id":5342}'
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

number

The ID of the job list.

item_id

required

number

The ID of the list item to delete.

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

GET /jobs/{job_id}/applications

List applications

Parameters
job_id

required

number

The ID of the job to return applications for.

page

required

number

The current page number of contacts to return.

per_page

required

number

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/1158/applications \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 238,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 7046,
        "description": "Porro distinctio assumenda minima.",
        "header": "Expedita voluptates corporis alias dolores voluptates iusto.",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/applications/{application_id}

Get an application

Parameters
application_id

required

number

The ID of the job application.

page

required

number

The current page number of contacts to return.

per_page

required

number

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/applications/1860 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7046,
  "description": "Porro distinctio assumenda minima.",
  "header": "Expedita voluptates corporis alias dolores voluptates iusto.",
  "_links": {...},
  "_embedded": {...}
}

GET /jobs/applications/{application_id}/fields

List application fields

Parameters
application_id

required

number

The ID of the job application.

page

required

number

The current page number of contacts to return.

per_page

required

number

The number of contacts to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/applications/9124/fields \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 892,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 8883,
        "title": "Explicabo eum ut atque ut molestiae ut.",
        "position": 0,
        "type": "text",
        "answers": [],
        "is_required": true,
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /jobs/{job_id}/tags

List all tags

Parameters
job_id

required

number

The ID of the job to return tags for.

page

required

number

The current page number of tags to return.

per_page

required

number

The number of tags to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/jobs/2369/tags \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 575,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 2307,
        "parent_id": 1931,
        "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

number

The ID of the job to replace tags on.

Body Parameters
tags

array

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

PUT /jobs/{job_id}/tags

Attach Tags

This will not delete any existing tags on the candidate.

Parameters
job_id

required

number

The ID of the job to attach tags to.

Body Parameters
tags

array

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

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

Delete Tag

Detaches an individual tag from the job.

Parameters
job_id

required

number

The ID of the job to detach the tag from.

tag_id

required

number

The ID of the tag to detach.

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

Users

GET /users

List all users

Parameters
page

required

number

The current page number of users to return.

per_page

required

number

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": 4091,
        "username": "Gisselle76@gmail.com",
        "first_name": "Johanna",
        "last_name": "Rowe",
        "title": "Future Accountability Analyst",
        "access_level: add_edit_delete": "",
        "_links": {...}
      },
      {...}
    ]
  }
}

GET /users/{id}

Get a user

Parameters
id

required

number

The ID of the user to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/users/4091 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 4091,
  "username": "Gisselle76@gmail.com",
  "first_name": "Johanna",
  "last_name": "Rowe",
  "title": "Future Accountability Analyst",
  "access_level: add_edit_delete": "",
  "_links": {...}
}

Pipelines

GET /pipelines

List all pipelines

Parameters
page

required

number

The current page number of pipelines to return.

per_page

required

number

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": 254,
  "_links": {...},
  "_embedded": {
    "pipelines": [
      {
        "id": 9336,
        "candidate_id": 4259,
        "job_id": 467,
        "rating": 3,
        "status_id": 5324,
        "date_created": "2015-02-13T13:36:27.979Z",
        "date_modified": "2015-04-30T02:18:45.694Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /pipelines/{id}

Get a pipeline

Parameters
id

required

number

The ID of the pipeline to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/pipelines/9336 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 9336,
  "candidate_id": 4259,
  "job_id": 467,
  "rating": 3,
  "status_id": 5324,
  "date_created": "2015-02-13T13:36:27.979Z",
  "date_modified": "2015-04-30T02:18:45.694Z",
  "_links": {...},
  "_embedded": {...}
}

POST /pipelines

Create a pipeline

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

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.

status_id

number

The ID of the status attached to this pipeline.

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

PUT /pipelines/{id}

Update a pipeline

Parameters
id

required

number

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.

status_id

number

The ID of the status attached to this pipeline.

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

DELETE /pipeline/{id}

Delete a pipeline

Parameters
id

required

number

The ID of the pipeline to delete.

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

GET /pipelines/statuses

List statuses

Parameters
page

required

number

The current page number of statuses to return.

per_page

required

number

The number of statuses to return per page.

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

GET /pipelines/statuses/{id}

Get a status

Parameters
id

required

number

The ID of the status to return.

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

POST /pipelines/{id}/status

Change status

Parameters
id

required

number

The ID of the pipeline 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/pipelines/2861/status \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"status_id":1624,"triggers":[{"id":1996,"fire":true}]}'
Example Response

Triggers

GET /triggers

List all triggers

Parameters
page

required

number

The current page number of triggers to return.

per_page

required

number

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

GET /triggers/{id}

Get a trigger

Parameters
id

required

number

The ID of the trigger to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/triggers/5178 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 5178,
  "description": "Send Candidate Status Change Notification",
  "is_required": false,
  "is_default": true,
  "_links": {...}
}

Attachments

GET /attachments/{id}

Get an attachment

Parameters
id

required

number

The ID of the attachment to return.

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

DELETE /attachment/{id}

Delete an attachment

Parameters
id

required

number

The ID of the attachment to delete.

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

GET /attachment/{id}/download

Download an attachment

Parameters
id

required

number

The ID of the attachment to download.

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

Work History

GET /work_history/{work_history_id}

Get a work history

Parameters
work_history_id

required

number

The ID of the work history to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/work_history/2441 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2936,
  "title": "Legacy Identity Developer",
  "candidate_id": 5219,
  "employer": {
    "linked": false,
    "name": "Fritsch - Von",
    "location": {
      "city": "Pabloborough",
      "state": "GA"
    }
  },
  "supervisor": {
    "linked": false,
    "name": "Nyasia",
    "phone": "(302) 548-1272"
  },
  "is_verified": true,
  "is_current": "false",
  "start_date": "2015-03-09T12:25:16.049Z",
  "end_date": "2015-11-02T04:47:23.750Z",
  "reason_for_leaving": "Est nemo aperiam error impedit."
}

PUT /work_history/{work_history_id}

Update a work history

Parameters
work_history_id

required

number

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/2441 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"title":"Dynamic Solutions Facilitator","employer":{"linked":false,"name":"Schimmel Group","location":{"city":"South Aubree","state":"GA"}},"supervisor":{"linked":false,"name":"Clyde","phone":"(515) 943-5399"},"is_verified":true,"is_current":"false","start_date":"2015-10-10T12:37:47.923Z","end_date":"2015-02-20T05:16:26.172Z","reason_for_leaving":"Nemo in sit similique sapiente qui dolorem at."}'
Example Response

DELETE /work_history/{work_history_id}

Delete a work history

Parameters
work_history_id

required

number

The ID of the work history to delete.

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

Portals

GET /portals

List all portals

Parameters
page

required

number

The current page number of portals to return.

per_page

required

number

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": 369,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 6324,
        "name": "Recusandae atque ad placeat quos enim reiciendis optio porro quis.",
        "date_created": "2015-03-06T12:32:21.473Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /portals/{id}

Get a portal

Parameters
id

required

number

The ID of the portal to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals/6324 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 6324,
  "name": "Recusandae atque ad placeat quos enim reiciendis optio porro quis.",
  "date_created": "2015-03-06T12:32:21.473Z",
  "_links": {...},
  "_embedded": {...}
}

GET /portals/{id}/jobs

List jobs

Parameters
id

required

number

The ID of the portal to return jobs for.

page

required

number

The current page number of jobs to return.

per_page

required

number

The number of jobs to return per page.

Example Request
curl -X GET \
https://api.catsone.com/v3/portals/6324/jobs \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "count": 25,
  "total": 233,
  "_links": {...},
  "_embedded": {
    "jobs": [
      {
        "id": 6191,
        "title": "Product Response Representative",
        "location": {
          "city": "Kihntown",
          "state": "MS",
          "postal_code": "73803-2006"
        },
        "description": "Ullam repellat consectetur neque dolores ut dolore. Et minus aperiam omnis commodi minus expedita quaerat aut voluptate. Distinctio consequatur repellat tempora sed. Veniam eos id minima.",
        "notes": "Neque alias dolorem praesentium rem.",
        "recruiter_id": 2079,
        "owner_id": 6542,
        "category": null,
        "is_hot": false,
        "start_date": "2015-10-29T02:52:36.494Z",
        "salary": null,
        "duration": "",
        "external_id": null,
        "company_id": 3033,
        "status_id": 6645,
        "date_created": "2015-03-15T07:36:03.774Z",
        "date_modified": "2015-07-03T20:02:49.195Z",
        "_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

number

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

job_id

required

number

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

Body Parameters
fields

array

An example with all fields types:

    {
        "fields": [
            {
                /* file */
 {
    "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/dropdown */
            "id": 524221
            "value":
Example Request
curl -X POST \
https://api.catsone.com/v3/portals/9890/jobs/5029 \
-H 'authorization: Token <Your API Key>' \
-H 'content-type: application/json' \
-d '{"fields":[{"id":9218,"value":"doloribus"}]}'
Example Response

Backups

GET /backups

List all backups

Parameters
page

required

number

The current page number of backups to return.

per_page

required

number

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": 306,
  "_links": {...},
  "_embedded": {
    "activities": [
      {
        "id": 7046,
        "status": "expired",
        "url": "https://madge.org",
        "file_size": 294516033,
        "started_by_id": 8704,
        "date_created": "2015-12-29T04:31:58.667Z",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /backups/{id}

Get a backup

Parameters
id

required

number

The ID of the backup to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/backups/789 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 7046,
  "status": "expired",
  "url": "https://madge.org",
  "file_size": 294516033,
  "started_by_id": 8704,
  "date_created": "2015-12-29T04:31:58.667Z",
  "_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":false}'
Example Response

Tags

GET /tags

List all tags

Parameters
page

required

number

The current page number of tags to return.

per_page

required

number

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": 575,
  "_links": {...},
  "_embedded": {
    "tags": [
      {
        "id": 2307,
        "parent_id": 1931,
        "title": "My Cool Tag Name",
        "_links": {...},
        "_embedded": {...}
      },
      {...}
    ]
  }
}

GET /tags/{id}

Get a tag

Parameters
id

required

number

The ID of the tag to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/tags/2307 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 2307,
  "parent_id": 1931,
  "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

number

The current page number of webhooks to return.

per_page

required

number

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": 812,
  "_links": {...},
  "_embedded": {
    "webhooks": [
      {
        "id": 802,
        "event": "candidate.created",
        "target_url": "https://mmountain.herokuapp.com/kAa5An56ew"
      },
      {...}
    ]
  }
}

GET /webhooks/{id}

Get a webhook

Parameters
id

required

number

The ID of the webhook to return.

Example Request
curl -X GET \
https://api.catsone.com/v3/webhooks/802 \
-H 'authorization: Token <Your API Key>'
Example Response
{
  "id": 802,
  "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, 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

number

The ID of the webhook to delete.

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