Jobs

A job represents a contact which you want to reach as part of a campaign.

Fields

class Job

address_lines: array: The postal address lines of the contact.

appointment: datetime: The date and time at which the contact should be called (optional). Only used for phone campaigns.

campaign: integer: The campaign the job belongs to.

city: string: The city of the contact.

country: string: The country of the contact.

created_at: datetime: The job’s creation date and time.

data: object: Arbitrary key / value data for this job (optional).

email: string: The e-mail address of the contact.

id: integer: The job’s unique ID.

label: string: The job’s business-specific label.

name: string: The name of the contact.

numbers: array: The contact’s phone numbers.

postal_code: string: The postal code of the contact.

reference: string: Your reference for this job (e.g. customer ID), which must be unique within the campaign.

state: integer

The current state of this job.

0 = queued
1 = calling
2 = succeeded
3 = failed
4 = cancelled

url: string: The URL at which this job can be viewed in your CRM (optional).

value: float: A monetary value for this job.

API

GET /j/jobs

Retrieves the list of jobs for a given campaign.

Example request:

GET /j/jobs?campaign=28 HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "address_lines": ["1 rue Toto"],
      "appointment": null,
      "campaign": 28,
      "city": "Paris",
      "country": "FR",
      "created_at": "2016-11-04T19:11:34.985Z",
      "data": {"some_property": "some value"},
      "email": "simon.dupont@example.com",
      "id": 14,
      "label": null,
      "name": "Simon Dupont",
      "numbers": ["+33123456789", "+33612345678"],
      "postal_code": "75001",
      "reference": "1234567",
      "state": 0,
      "url": "https://crm.example.com/customers/1234567",
      "value": 123.45
   }
]

Request Headers:

Authorization – OAuth token to authenticate

Query Parameters:

campaign (integer) – A campaign ID. Required unless modified_since is specified.
modified_since (datetime) – An optional date and time in the past 48 hours. If specified, only jobs modified since this moment then will be returned.

Response JSON Array of Objects:

address_lines (array) – The postal address lines of the contact.
appointment (datetime) – The date and time at which the contact should be called (optional). Only used for phone campaigns.
campaign (integer) – The campaign the job belongs to.
city (string) – The city of the contact.
country (string) – The country of the contact.
created_at (datetime) – The job’s creation date and time.
data (object) – Arbitrary key / value data for this job (optional).
email (string) – The e-mail address of the contact.
id (integer) – The job’s unique ID.
label (string) – The job’s business-specific label.
name (string) – The name of the contact.
numbers (array) – The contact’s phone numbers.
postal_code (string) – The postal code of the contact.
reference (string) – Your reference for this job (e.g. customer ID), which must be unique within the campaign.
state (integer) – The current state of this job.
url (string) – The URL at which this job can be viewed in your CRM (optional).
value (float) – A monetary value for this job.

Status Codes:

200 OK – no error
400 Bad Request – for instance a required field is missing
403 Forbidden – you tried to access a forbidden resource, check you provided a valid OAuth token

POST /j/jobs

Adds a job to an existing campaign.

Example request:

POST /j/jobs HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

{
   "campaign": 28,
   "data": {"some_property": "some value"},
   "email": "simon.dupont@example.com",
   "name": "Simon Dupont",
   "numbers": ["0123456789", "0612345678"],
   "reference": "1234567",
   "url": "https://crm.example.com/customers/1234567",
   "value": 123.45
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
   "address_lines": [],
   "appointment": null,
   "campaign": 28,
   "city": null,
   "country": null,
   "created_at": "2016-11-04T19:11:34.985Z",
   "data": {"some_property": "some value"},
   "email": "simon.dupont@example.com",
   "id": 14,
   "label": null,
   "name": "Simon Dupont",
   "numbers": ["+33123456789", "+33612345678"],
   "postal_code": null,
   "reference": "1234567",
   "state": 0,
   "url": "https://crm.example.com/customers/1234567",
   "value": 123.45
}

Request Headers:

Authorization – OAuth token to authenticate

Request JSON Object:

address_lines (array) – The postal address lines of the contact.
appointment (datetime) – The date and time at which the contact should be called (optional). Only used for phone campaigns.
campaign (integer) – The campaign the job belongs to.
city (string) – The city of the contact.
country (string) – The country of the contact.
data (object) – Arbitrary key / value data for this job (optional).
email (string) – The e-mail address of the contact.
name (string) – The name of the contact.
numbers (array) – The contact’s phone numbers.
postal_code (string) – The postal code of the contact.
reference (string) – Your reference for this job (e.g. customer ID), which must be unique within the campaign.
url (string) – The URL at which this job can be viewed in your CRM (optional).
value (float) – A monetary value for this job.

Response JSON Object:

address_lines (array) – The postal address lines of the contact.
appointment (datetime) – The date and time at which the contact should be called (optional). Only used for phone campaigns.
campaign (integer) – The campaign the job belongs to.
city (string) – The city of the contact.
country (string) – The country of the contact.
created_at (datetime) – The job’s creation date and time.
data (object) – Arbitrary key / value data for this job (optional).
email (string) – The e-mail address of the contact.
id (integer) – The job’s unique ID.
label (string) – The job’s business-specific label.
name (string) – The name of the contact.
numbers (array) – The contact’s phone numbers.
postal_code (string) – The postal code of the contact.
reference (string) – Your reference for this job (e.g. customer ID), which must be unique within the campaign.
state (integer) – The current state of this job.
url (string) – The URL at which this job can be viewed in your CRM (optional).
value (float) – A monetary value for this job.

Status Codes:

201 Created – no error
400 Bad Request – for instance a required field is missing
403 Forbidden – you tried to access a forbidden resource, check you provided a valid OAuth token

GET /j/jobs/:id

Retrieves the specified job.

Example request:

GET /j/jobs/14 HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "address_lines": ["1 rue Toto"],
   "appointment": null,
   "campaign": 28,
   "city": "Paris",
   "country": "FR",
   "created_at": "2016-11-04T19:11:34.985Z",
   "data": {"some_property": "some value"},
   "email": "simon.dupont@example.com",
   "id": 14,
   "label": null,
   "name": "Simon Dupont",
   "numbers": ["+33123456789", "+33612345678"],
   "postal_code": "75001",
   "reference": "1234567",
   "state": 0,
   "url": "https://crm.example.com/customers/1234567",
   "value": 123.45
}

Request Headers:

Authorization – OAuth token to authenticate

Response JSON Object:

address_lines (array) – The postal address lines of the contact.
appointment (datetime) – The date and time at which the contact should be called (optional). Only used for phone campaigns.
campaign (integer) – The campaign the job belongs to.
city (string) – The city of the contact.
country (string) – The country of the contact.
created_at (datetime) – The job’s creation date and time.
data (object) – Arbitrary key / value data for this job (optional).
email (string) – The e-mail address of the contact.
id (integer) – The job’s unique ID.
label (string) – The job’s business-specific label.
name (string) – The name of the contact.
numbers (array) – The contact’s phone numbers.
postal_code (string) – The postal code of the contact.
reference (string) – Your reference for this job (e.g. customer ID), which must be unique within the campaign.
state (integer) – The current state of this job.
url (string) – The URL at which this job can be viewed in your CRM (optional).
value (float) – A monetary value for this job.

Status Codes:

200 OK – no error
403 Forbidden – you tried to access a forbidden resource, check you provided a valid OAuth token
404 Not Found – the requested resource was not found

POST /j/jobs/:id/unqueue

Requests that the specified job not be called anymore.

If this was the last active job for its campaign, the campaign will be deactivated.

Example request:

POST /j/jobs/14/unqueue HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "address_lines": ["1 rue Toto"],
   "appointment": null,
   "campaign": 28,
   "city": "Paris",
   "country": "FR",
   "created_at": "2016-11-04T19:11:34.985Z",
   "data": {"some_property": "some value"},
   "email": "simon.dupont@example.com",
   "id": 14,
   "label": null,
   "name": "Simon Dupont",
   "numbers": ["+33123456789", "+33612345678"],
   "postal_code": "75001",
   "reference": "1234567",
   "state": 3,
   "url": "https://crm.example.com/customers/1234567",
   "value": 123.45
}

Bulk API

These APIs make it possible to efficiently perform bulk operations on up to 1000 jobs per call.

POST /j/jobs/bulk/create

Adds jobs to existing campaigns.

Example request:

POST /j/jobs/bulk/create HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

[
   {
      "campaign": 28,
      "data": {"some_property": "some value"},
      "email": "simon.dupont@example.com",
      "name": "Simon Dupont",
      "numbers": ["0123456789", "0612345678"],
      "reference": "1234567",
      "url": "https://crm.example.com/customers/1234567",
      "value": 123.45
   },
   {
      "campaign": 28,
      "data": {"some_property": "other value"},
      "email": "alice.schmitt@example.com",
      "name": "Mme. Schmitt",
      "numbers": ["0234567890"],
      "reference": "2345678",
      "url": "https://crm.example.com/customers/2345678",
      "value": 234.56
   }
]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "data": {
         "address_lines": [],
         "appointment": null,
         "campaign": 28,
         "city": null,
         "country": null,
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {"some_property": "some value"},
         "email": "simon.dupont@example.com",
         "id": 14,
         "label": null,
         "name": "Simon Dupont",
         "numbers": ["+33123456789", "+33612345678"],
         "postal_code": null,
         "reference": "1234567",
         "state": 0,
         "url": "https://crm.example.com/customers/1234567",
         "value": 123.45
      },
      "status_code": 201
   },
   {
      "data": {
         "address_lines": [],
         "appointment": null,
         "campaign": 28,
         "city": null,
         "country": null,
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {"some_property": "some value"},
         "email": "alice.schmitt@example.com",
         "id": 15,
         "label": null,
         "name": "Mme. Dupont",
         "numbers": ["+33234567890"],
         "postal_code": null,
         "reference": "2345678",
         "state": 0,
         "url": "https://crm.example.com/customers/2345678",
         "value": 234.56
      },
      "status_code": 201
   }
]

POST /j/jobs/bulk/patch

Updates existing jobs.

Only the specified attributes will be updated, following PATCH semantics.

Example request:

POST /j/jobs/bulk/patch HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

[
   {
      "id": 14,
      "numbers": ["+33123456789", "+33623456789"]
   },
   {
      "city": "Fooville",
      "id": 15
      "name": "Echo Foxtrot"
      "postal_code": "12345"
   },
   {
      "id": 16
      "name": "Doesn't exist!"
   }
]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "data": {
         "address_lines": [],
         "appointment": null,
         "campaign": 28,
         "city": "Paris",
         "country": "FR",
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {"some_property": "some value"},
         "email": "simon.dupont@example.com",
         "id": 14,
         "label": null,
         "name": "Simon Dupont",
         "numbers": ["+33123456789", "+33623456789"]
         "postal_code": null,
         "reference": "1234567",
         "state": 0,
         "url": "https://crm.example.com/customers/1234567",
         "value": 123.45
      },
      "status_code": 200
   },
   {
      "data": {
         "address_lines": [],
         "appointment": null,
         "campaign": 28,
         "city": "Fooville",
         "country": null,
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {},
         "email": "echo.foxtrot@example.com",
         "id": 15,
         "label": null,
         "name": "Echo Foxtrot",
         "numbers": ["+33234567890"],
         "postal_code": "12345"
         "reference": "2345679",
         "state": 0,
         "url": "https://crm.example.com/customers/2345678",
         "value": 234.56
      },
      "status_code": 200
   },
   {
      "data": null,
      "status_code": 404
   }
]

POST /j/jobs/bulk/unqueue

Requests that the specified jobs not be called anymore.

If any campaigns do not have any active jobs left, they will be deactivated.

Example request:

POST /j/jobs/bulk/unqueue HTTP/1.1
Authorization: Bearer 0a1b2c3d4e5f
Content-Type: application/json

[
   {
      "id": 14
   },
   {
      "id": 15
   }
]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
   {
      "data": {
         "address_lines": ["1 rue Toto"],
         "appointment": null,
         "campaign": 28,
         "city": "Paris",
         "country": "FR",
         "created_at": "2016-11-04T19:11:34.985Z",
         "data": {"some_property": "some value"},
         "email": "simon.dupont@example.com",
         "id": 14,
         "label": null,
         "name": "Simon Dupont",
         "numbers": ["+33123456789", "+33612345678"],
         "postal_code": "75001",
         "reference": "1234567",
         "state": 3,
         "url": "https://crm.example.com/customers/1234567",
         "value": 123.45
      },
      "status_code": 200
   },
   {
      "data": null,
      "status_code": 404
   }
]