NAV Navbar
Logo
PHP

Introduction

Welcome to the Jobbers One API!

To use our API you have to contact Jobbers so that they can provide you with the credentials (API key and secret API key) to access these services.

The Jobbers API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors.

We are using Authentication in all of our requests.

Take care that all this documentation refers to the endpoints without the base URL. You have to add it in every call. In general, it will be: 

    REST base URL

    https://www.jobbers.com

Code examples

Examples in this documentation are provided in PHP code.

Regarding PHP, when explaining every endpoint we’ll use a call to the following functions:

All of them are based on cURL. These functions are described below.

PHP GET

This is a simple GET using cURL.

Note that:

<?php

function doGet($endpoint, $bearer) {

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => BASE_URL . $endpoint,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer ' . $bearer
    ),
  ));

  //  exec the request
  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);

  return array($err, $response);
}

//  When calling doGet:
list($err, $response) = doGet($url, ACCESS_TOKEN);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

PHP POST

This is a simple POST using cURL.

Note that:

<?php

function doPost($endpoint, $payload, $bearer = null) {

  $curl = curl_init();

  $headers = array();
  $headers[] = 'Content-type: application/json';
  if ($bearer != null) {
    $headers[] = 'Authorization: Bearer ' . $bearer;
  }

  curl_setopt_array($curl, array(
    CURLOPT_URL => BASE_URL . $endpoint,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => $headers
  ));

  //  exec the request
  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);

  return array($err, $response);
}


//  When calling doPost:
list($err, $response) = doPost($url, $payload, ACCESS_TOKEN);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

PHP DELETE

This is a simple DELETE using cURL.

Note that:

<?php

function doDelete($endpoint, $bearer) {

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => BASE_URL . $endpoint,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => array(
      'Authorization: Bearer ' . $bearer
    ),
  ));

  $response = curl_exec($curl);
  $err = curl_error($curl);
  curl_close($curl);

  return array($err, $response);
}

//  when calling doDelete
list($err, $response) = doDelete($url, ACCESS_TOKEN);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Authentication

Jobbers API uses API keys to allow access to the API and encryption to protect the data sent. In fact, we are using a very light version of Oauth2 to authenticate users.

As Jobbers collaborator, you’ll be given an API key and an API secret key. You have to use both fields to authenticate yourself to a unique endpoint. Once authenticated you’ll be given an access_token valid for a certain time. You’ll have to provide this access_token in every other request authentication header.

Every time you’ll use this access_token, its expiration time will be renewed. Right now, we are not supporting a refresh_token, so if the token has expired you’ll be forced to authenticate again to get a new access_token.

Oauth2

Oauth2 is a simple mechanism that allows an API to authenticate users or grant access to third users. In our case, we are only authenticating direct users and that’s why the process is pretty simple.

  1. POST your API KEY and API SECRET KEY to our authentication endpoint
  2. Receive an access_token as response if all above fields are correct
  3. Use this access_token to authenticate the rest of call

Look the authentication area in this documentation for full understanding on this process.

Once you are given an access_token, you have to send it in all requests. Jobbers API expects for the access_token to be included in a header that looks like the following:

Authorization: Bearer ACCESS_TOKEN

GET /oneapi/v0/echo HTTP/1.1
Authorization: Bearer ACCESS_TOKEN

{
    "data": "echo"
}


<?php

... 

curl_setopt_array($curl, array(
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer ACCESS_TOKEN",
    ...
  ),
));

...

Errors

HTTP status

The Jobbers One API uses the following error codes:

Error Code Meaning
400 Bad Request – The server cannot process the request due to something perceived to be a client error
401 Unauthorized – Your API key / ACCESS_TOKEN is wrong
403 Forbidden – Not permitted to access this endpoint
404 Not Found – The specified endpoint cannot be found
405 Method Not Allowed – You tried to access and endpoint with an invalid method
422 Unprocessable Entity - The message cannot be decoded
500 Internal Server Error – An error occurred on our servers. Please try again later.
503 Service Unavailable – The service is temporarially offline (e.g., for maintenance). Please try again later. 
<?php

//  If you need the retrieve the status code from a cURL operation:
...
$response = curl_exec($curl);
$httpcode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
...

Error Names

When in 404, 405 and, especially, 400 the API can return a body with some help messages. These messages have the following structure:

{ "errors": [{ "title": "is_invalid", "source": "client", "detail": "client not found" }] }

It’s an array of errors containg objects composed by three components:

Field Meaning
title From a set of possible values: cannot_be_blank, has_already_been_taken, must_be_accepted, is_invalid, does_not_match, cannot_be_empty
source Field causing the error
detail A more human readable error message

Echo endpoints

These endpoints are for TESTING. You can use them to test authentication as they provide you with a simple API to test both of them.

Getting Echo

This endpoint is for TESTING purposes and it’s not ruled following REST standards as it just echoes the input given.

HTTP Request

GET /oneapi/v0/echo/{text}

GET /oneapi/v0/echo/hello+world HTTP/1.1
Authorization: Bearer ACCESS_TOKEN

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "data": "echo hello world"
}

URL parameters

Parameter Mandatory Description
text No If set, the endpoint echoes the text.

Remember that URL parameters should always be urlencoded.

Response

The {text} passed in the URL parameter is output in the following format:

{ "data": "echo {text}" }

Posting Echo

This endpoint is for TESTING purposes and it’s not ruled following REST standards as it just echoes the input given.

HTTP Request

POST /oneapi/v0/echo

POST /oneapi/v0/echo HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "text": "hello world"
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
  "data": "echo hello world"
}

Body parameters (as JSON)

Parameter Mandatory Description
text No If set, the endpoint echoes the text.

Response

Same output as GET Echo.

(we know that this is not REST compliant, but these two endpoints are only for TESTING).

Authentication

Get Access Token

Sends the API key and API Secret Key to authenticate and receives an access_token to use in the rest of endpoints.

HTTP Request

POST /oneapi/authentication/token

<?php

  $payload = array(
    'grant_type' => 'password',
    'username' => API_KEY,
    'password' => API_SECRET_KEY
  );

  $url = '/oneapi/authentication/token';

  //  This function encapsulates the curl method
  list($err, $response) = doPost($url, $payload);

Body parameters (as JSON)

Parameter Mandatory Description Comment
grant_type Yes Type of request string, always set to ‘password’
username Yes Username (commonly the API key) string
password Yes Password (commonly the API Secret key) string

Response

A JSON like: { "access_token": "87eb6f50-d0e2-45d5-ab18-526b60bfc74c", "token_type": "bearer", "expires_in": 3600 }

Field Description Comment
access_token Token to use in endpoints to authenticte the request
token_type Always set to ‘bearer’
expires_in Seconds of validation of this token

Get Current Authenticated

Sometimes you need to retrieve some information of the entity being authenticated with your access_token. Some information retrieved by this method is needed for some other endpoints.

HTTP Request

GET /oneapi/v0/current

<?php
  $url = '/oneapi/v0/current';

  //  This function encapsulates the curl method
  list($err, $response) = doGet($url, ACCESS_TOKEN);

Response

A JSON like: { "data": { "enterprise_id": "20" } }

Field Description Comment
enterprise_id Id of the enterprise this authenticate request belongs to. int

Oauth2 External Login

App Login from a third party web functionality. If you want to login from a third party web and retrieve some login information you could use grant_type="authorization_code". Copy example code into a file and open it with a simple webserver, e.g.: "php -S localhost:9099"

Check External Login Example code at side bar

Enterprises

Get Groups of Enterprise

An enterprise in Jobbers can be composed by groups. This endpoint retrieves the groups of the enterprise being authenticated.

HTTP Request

GET /oneapi/v0/groupsofenterprises

<?php

  $url = '/oneapi/v0/groupsofenterprises';
  list($err, $response) = doGet($url, ACCESS_TOKEN);

Response

A JSON like: { "data": [ { "group_id": 373, "name": "Sous conciergerie #1 Demonstration" }, { "group_id": 374, "name": "Sous conciergerie #2 Demonstration" } ] }

Field Description Comment
group_id Id of the group of enterprise int
name Name of the gorup of enterprise string

Get Stats

This endpoint gets the usage statistics of the enterprise being authenticated corresponding to a certain period (month and year).

HTTP Request

GET /oneapi/v0/stats?month=7&year=2018

<?php

  $url = sprintf('/oneapi/v0/stats?month=%s&year=%s', urlencode($month), urlencode($year));
  list($err, $response) = doGet($url, ACCESS_TOKEN);

URL Parameters

Parameter Mandatory Description Comment
month Yes Month between 1 and 12
year Yes Year in 4 digits

Response

A JSON like: { "data": [ { "group_id": null, "last_updated": "2018-09-03 18:33:43", "total_requests": 52, "delta_requests": 52, "total_passes": 0, "delta_passes": 0, "total_clients": 10, "delta_clients": 10, "percentage_female_clients": 0, "percentage_male_clients": 20, "percentage_unknown_clients": 80, "nologin_clients": { "total": 10, "emails": [ "client+1@clients.jobbers.com", "oriol.marti+3@gmail.com", "oriol.marti+5@gmail.com", "oriol.marti+6@gmail.com", "oriol.marti+7@gmail.com", "oriol.marti+8@gmail.com", "oriol.marti+9@gmail.com", "oriol.marti+10@gmail.com", "oriol.marti+11@gmail.com", "oriol.marti+14@gmail.com" ] }, "tags": [ { "tag_name": "sports", "percent": 0 }, { "tag_name": "enfants", "percent": 0 }, { "tag_name": "voyages", "percent": 0 }, { "tag_name": "services_domicile", "percent": 0 }, { "tag_name": "services_individus", "percent": 82.61 }, { "tag_name": "animaux", "percent": 0 }, { "tag_name": "auto_moto", "percent": 4.35 }, { "tag_name": "coaching", "percent": 0 }, { "tag_name": "livraison", "percent": 0 }, { "tag_name": "administratif", "percent": 0 }, { "tag_name": "demenagement", "percent": 0 }, { "tag_name": "anniversaire", "percent": 8.7 }, { "tag_name": "mariage_pacs", "percent": 0 }, { "tag_name": "evg", "percent": 0 }, { "tag_name": "romantique", "percent": 0 }, { "tag_name": "fetes", "percent": 0 }, { "tag_name": "reservation", "percent": 0 }, { "tag_name": "marketplace", "percent": 0 }, { "tag_name": "recherches", "percent": 4.35 }, { "tag_name": "medical", "percent": 0 }, { "tag_name": "bons_plans", "percent": 0 } ], "avergage_conversation_rating": 0, "total_orders": { "total": 0, "categories": [ { "category_id": "2", "category_name": "Accueil", "percent": 0.28 }, { "category_id": "21", "category_name": "Repassage-MyPressing", "percent": 3.43 } ] } }, { "group_id": 373, "last_updated": "2018-09-03 18:33:45", "total_requests": 0, "delta_requests": 0, "total_passes": 1, "delta_passes": 1, "total_clients": 0, "delta_clients": 0, "percentage_female_clients": 0, "percentage_male_clients": 20, "percentage_unknown_clients": 80, "nologin_clients": { "total": 0, "emails": [] }, "tags": [ { "tag_name": "sports", "percent": 0 }, { "tag_name": "enfants", "percent": 0 }, { "tag_name": "voyages", "percent": 0 }, { "tag_name": "services_domicile", "percent": 0 }, { "tag_name": "services_individus", "percent": 82.61 }, { "tag_name": "animaux", "percent": 0 }, { "tag_name": "auto_moto", "percent": 4.35 }, { "tag_name": "coaching", "percent": 0 }, { "tag_name": "livraison", "percent": 0 }, { "tag_name": "administratif", "percent": 0 }, { "tag_name": "demenagement", "percent": 0 }, { "tag_name": "anniversaire", "percent": 8.7 }, { "tag_name": "mariage_pacs", "percent": 0 }, { "tag_name": "evg", "percent": 0 }, { "tag_name": "romantique", "percent": 0 }, { "tag_name": "fetes", "percent": 0 }, { "tag_name": "reservation", "percent": 0 }, { "tag_name": "marketplace", "percent": 0 }, { "tag_name": "recherches", "percent": 4.35 }, { "tag_name": "medical", "percent": 0 }, { "tag_name": "bons_plans", "percent": 0 } ], "avergage_conversation_rating": 0, "total_orders": { "total": 0, "categories": [] } }, { "group_id": 374, "last_updated": "2018-09-03 18:33:46", "total_requests": 0, "delta_requests": 0, "total_passes": 0, "delta_passes": 0, "total_clients": 0, "delta_clients": 0, "percentage_female_clients": 0, "percentage_male_clients": 20, "percentage_unknown_clients": 80, "nologin_clients": { "total": 0, "emails": [] }, "tags": [ { "tag_name": "sports", "percent": 0 }, { "tag_name": "enfants", "percent": 0 }, { "tag_name": "voyages", "percent": 0 }, { "tag_name": "services_domicile", "percent": 0 }, { "tag_name": "services_individus", "percent": 82.61 }, { "tag_name": "animaux", "percent": 0 }, { "tag_name": "auto_moto", "percent": 4.35 }, { "tag_name": "coaching", "percent": 0 }, { "tag_name": "livraison", "percent": 0 }, { "tag_name": "administratif", "percent": 0 }, { "tag_name": "demenagement", "percent": 0 }, { "tag_name": "anniversaire", "percent": 8.7 }, { "tag_name": "mariage_pacs", "percent": 0 }, { "tag_name": "evg", "percent": 0 }, { "tag_name": "romantique", "percent": 0 }, { "tag_name": "fetes", "percent": 0 }, { "tag_name": "reservation", "percent": 0 }, { "tag_name": "marketplace", "percent": 0 }, { "tag_name": "recherches", "percent": 4.35 }, { "tag_name": "medical", "percent": 0 }, { "tag_name": "bons_plans", "percent": 0 } ], "avergage_conversation_rating": 0, "total_orders": { "total": 0, "categories": [] } }, ] }

The same structure is repeated for the enterprise and the groups of the enterprise (in case they exists).

Field Description Comment
group_id Id of the group of the enterprise (null when the main enterprise)
last_updated Datetime of the stats calculation Format Y-m-d H:i:s
total_requests Requests are the interactions between a Jobbers Agent and a Jobbers Client. This amount is the aggregated requests for this enterprise or group
delta_requests Requests done in this period
total_passes Passes are the “bypass” tokens used to register or keep registered in the Jobbers area. This amount is the aggregated used passes for this enterprise or group
delta_passes Passes used in this period
total_clients Clients registered to this enterprise or group
delta_clients Clients registered in this period
percentage_female_clients Clients registered as female, as percent Double
percentage_male_clients Clients registered as male, as percent Double
percentage_unknown_clients Clients registered with unknown sex, as percent Double
nologin_clients.total Clients that has not yet perform a login in Jobbers
nologin_clients.emails List of the mails that haven’t yet perform a login in Jobbers
tags.tag_name Name of the label assigned to a conversation. A conversation is a thread of interactions between a Jobbers Agent and a Jobbers Client.
tags.percent Percent of the usage of this tag in conversations Double
avergage_conversation_rating Clients can rate a conversation. This is the average of these ratings Double
total_orders.total Amount of purchases performed by Jobbers clients belonging to this enterprise or group
total_orders.categories.category_id Id of the category owning products being purchased
total_orders.categories.category_name Name of the category owning products being purchased
total_orders.categories.percent Percent of the productes belonging to this category being purchased

Stock of Passes

Get Stock of Passes of Enterprise

Gets the stock of passes available belonging to the authenticated enterprise.

HTTP Request

GET /oneapi/v0/stockofpasses

<?php

  $url = '/oneapi/v0/stockofpasses';
  list($err, $response) = doGet($url, ACCESS_TOKEN);

Response

A JSON like: { "data": [ { "stock_id": 53, "description": "single pass 2", "duration": 1, "duration_type": "YEAR", "expiration_date": "2018-07-30 23:59:59", "total_units": 3, "total_available": 3, "total_used": 0, "price": 0, "net_price": 0, "vat": 0 }, { "stock_id": 52, "description": "single pass", "duration": 1, "duration_type": "YEAR", "expiration_date": "2018-12-27 23:59:59", "total_units": 10, "total_available": 10, "total_used": 0, "price": 10.1, "net_price": 10, "vat": 10 } ] }

Field Description Comment
stock_id Id of the stock int
description Name of the stock string
duration Integer int
duration_type DAY/MONTH/YEAR, in combination with the duration field string
expiration_date datetime until the stock will be available Format Y-m-d H:i:s
total_units total units in the stock int
total_available total available in the stock int
total_used total already used in the stock int
price total price (including vat and base price) float
net_price total net price (without vat) float
vat percent of vat int

Assign Pass to Client

This endpoint assigns a pass available from a stock of passes to the given client

HTTP Request

POST /oneapi/v0/stockofpasses/assign

<?php

  $payload = array(
    'email' => 'client@clients.jobbers.com',
    'stock_id' => 52,
    'payment_reference' => 'payment_reference_01'
  );

  $url = '/oneapi/v0/stockofpasses/assign';

  //  This function encapsulates the curl method
  list($err, $response) = doPost($url, $payload);

Body parameters (as JSON)

Parameter Mandatory Description Comment
email Yes Client email string
stock_id Yes Id of the stock to get the pass from int
payment_reference Yes External Id to identiy this transaction, provided by your own mechanism. Must be unique string

Response

{ "data": { "end_subscription_date": "2021-09-09 23:59:59" } }

Field Description Comment
end_subscription_date The new end of subscription date calculated using this pass Format Y-m-d H:i:s

Invoice of a Pass Assignment

This endpoint generates a URL with the invoice corresponding to a pass assignment.

HTTP Request

POST /oneapi/v0/stockofpasses/invoice

NOT IMPLEMENTED YET

Body parameters (as JSON)

Parameter Mandatory Description Comment
payment_reference Yes External reference to identify the transaction, provided by you. Must be unique string
first_name Yes First name to appear in the invoice string
last_name Yes Last name to appear in the invoice string
address Yes Address to appear in the invoice string
zip_code Yes Zip code to appear in the invoice string
city  Yes City to appear in the invoice string
country Yes Country to appear in the invoice string

Response

NOT IMPLEMENTED YET

Clients

Checking Email Exists

Cheks wether the given email exists or not as a client registered in Jobbers.

HTTP Request

GET /oneapi/v0/clients/{clientEmail}/exists

<?php

  $email = urlencode("client@clients.jobbers.com");

  $url = sprintf('/oneapi/v0/clients/%s/exists', $client));
  list($err, $response) = doGet($url, ACCESS_TOKEN);

URL parameters

Parameter Mandatory Description
clientEmail Yes Email to check

Remember that URL parameters should always be urlencoded.

Response

A JSON like: { "data": { "exists": true, "movable": false, "attached_to_another_enterprise": false, "subscription_valid": true, "client_active": true } }

Field Description Comment
exists true if email is registered in Jobbers boolean
movable true if email can be moved to your enterprise boolean
attached_to_another_enterprise true if email belongs to an enterprise other than yours boolean
subscription_valid true if email has a valid subscription boolean
client_active true if email belongs to an active client boolean

Getting a Client

Gets all data of the client given his email. You can perform this operation passing the clientId or the clientEmail.

HTTP Request

GET /oneapi/v0/clients/{clientIdOrClientEmail}

<?php

  $email = urlencode("client@clients.jobbers.com");

  $url = sprintf('/oneapi/v0/clients/%s', $client));
  list($err, $response) = doGet($url, ACCESS_TOKEN);

URL parameters

Parameter Mandatory Description
clientId Yes/No Id of the client to update
clientEmail No/Yes Email of the client to update

Remember that URL parameters should always be urlencoded.

Response

A json like: { "data": { "client_id": 40331, "email": "client@clients.jobbers.com", "first_name": "prenom", "last_name": "nom", "phone_prefix": "+33", "phone": "987654321", "gender": "FEMALE", "address": "32 rue des volontaires", "zip_code": "75015", "city": "Paris", "country": "FR", "cgu": true, "optin": false, "registering_date": "2018-07-12 10:09:24", "last_login_date": null, "end_subscription_date": "2018-09-09 14:37:03", "active": true, "group_id": 374 } }

Field Description Comment
client_id Inner id of the client int
email Email string
first_name Name string
last_name Surname string
phone_prefix International phone number prefix string
phone Telephone number string
gender MALE or FEMALE string
address Address string
zip_code Postal code string
city City string
country ISO (two letter) country string
cgu General conditions acceptance boolean
optin Send outbound emailings boolean
registering_date Date of register Format Y-m-d H:i:s
last_login_date Date of last login Format Y-m-d H:i:s
end_subscription_date Date of end of subscription Format Y-m-d H:i:s
active Status boolean
group_id group inside the enterprise the client belongs to integer

Creating Client

Creates a new client in Jobbers that belongs to the enterprise being authenticated.

HTTP Request

POST /oneapi/v0/clients

<?php

  $payload = array(
    'email' => 'client@clients.jobbers.com',
    'group_id' => 372,
    'first_name' => 'prenom',
    'last_name' => 'nom',
    'phone_prefix' => '+33',
    'phone' => '987654321',
    'address' => '32 rue des voluntaires',
    'zip_code' => '75015',
    'city' => 'Paris',
    'country' => 'FR',
    'optin' => true,
    'cgu' => true,
    'gender' => 'FEMALE'
  );

  //  prepare the url
  $url = '/oneapi/v0/clients';
  list($err, $response) = doPost($url, $payload, ACCESS_TOKEN);

Body parameters (as JSON)

Parameter Mandatory Description Comment
email Yes Email string
group_id No Enterprise group belonging to string
first_name Yes Name string
last_name Yes Surname string
phone_prefix Yes International phone prefix string
phone Yes Telephone number string
address Yes Address string
zip_code Yes Postal code string
city Yes City string
country Yes ISO 3166-1 alpha-2 codes string
cgu Yes General conditions acceptance must be true
optin Yes Send outbound emailings true/false
gender No MALE/FEMALE constants string

Response

A JSON like:

{ "data": { "client_id": 40331, "email": "client@clients.jobbers.com", "first_name": "prenom", "last_name": "nom", "phone_prefix": "+33", "phone": "987654321", "gender": "FEMALE", "address": "32 rue des volontaires", "zip_code": "75015", "city": "Paris", "country": "FR", "cgu": true, "optin": false, "registering_date": "2018-07-12 10:09:24", "last_login_date": null, "end_subscription_date": "2018-09-09 14:37:03", "active": true, "group_id": 374, "password": "G*zyn9L>" } }

It’s the same output as the operation Getting a Client but with an added field:

Field Description Comment
password Automatic random password You can use it or not depending on what interactions are done with this client

Updating a Client

Updates an existing client in Jobbers. You can perform this operation passing the clientId or the clientEmail.

HTTP Request

POST /oneapi/v0/clients/{clientIdOrClientEmail}

<?php

  $payload = array(
    "email" => "client@clients.jobbers.com",
    "group_id" => 373,
    "first_name" => "prenom2",
    "last_name" => "nom2",
    "phone_prefix" => "+33",
    "phone" => "176440400",
    "street" => "32 rue des volontaires",
    "zip_code" => "75015",
    "gender" => "MALE",
    "city" => "Paris",
    "country" => "FR",
    "optin" => true
  );

  //  prepare the url
  $email = urlencode("client@clients.jobbers.com");
  $url = sprintf('/oneapi/v0/clients/%s', $client));

  list($err, $response) = doPost($url, $payload, ACCESS_TOKEN);

URL parameters

Parameter Mandatory Description
clientId Yes/No Id of the client to update
clientEmail No/Yes Email of the client to update

Remember that URL parameters should always be urlencoded.

Body parameters (as JSON)

Same input as creating a client except the CGU field which is no needed anymore

Response

A JSON like the on in Getting a Client.

Deleting Client

Deletes an existing client in Jobbers

HTTP Request

DELETE /oneapi/v0/clients/{clientIdOrClientEmail}

<?php

  //  prepare the url
  $email = urlencode("client@clients.jobbers.com");
  $url = sprintf('/oneapi/v0/clients/%s', $client));

  list($err, $response) = doDelete($url, ACCESS_TOKEN);

URL parameters

Parameter Mandatory Description
clientId Yes/No Id of the client to update
clientEmail No/Yes Email of the client to update

Remember that URL parameters should always be urlencoded.

Response

A JSON like: { "data": { "leaving_date":"2018-07-12 11:18:44" } }

Autologin Client

Enables a client to log in Jobbers. This a two step process. You have to:

  1. Ask for a token for this client to login Jobbers. This token is valid to be used only 1 time and in one hour max.
  2. Redirect the client to a link using this token.

If the token is not valid the user will be redirected to the jobbers landing page. If the log in is correct, user will be redirected to the jobbers’ client landing page.

1. Get a Token

HTTP Request

GET /oneapi/v0/clients/{clientIdOrClientEmail}/login

<?php

  //  prepare the url
  $email = urlencode("client@clients.jobbers.com");
  $url = sprintf('/oneapi/v0/clients/%s/login', $client));

  list($err, $response) = doGet($url, ACCESS_TOKEN);

Response

A JSON like: { "data": { "url": "https://www.jobbers.com/oneappweb/?token=3f2dcc2fce47f959f3519ec43648cc31df67e9a0de40f95c1ccbba24b519aec0" } }

2. Redirect client

You have to redirect your client to the url you have received from the point above:

Redirect to URL

<?php

  //  get the url following the above instructions
  $url = URL;

  header('Location: ' . $url);
  exit();

Conversations

Enables conversations, messages and webhooks for conversations with jobbers.

New Conversation

Creates a new conversation

HTTP Request

POST /api/v0/conversations

Body parameters in a JSON

Parameter Mandatory Description
client_id Yes Client id who creates the conversation
subject Yes Subject for the conversation

{ "client_id" : 12399, "subject": "New conversation test" }

Response

Response is a JSON

{ "id": 83830, "client_id": 12399, "creation_date": "2021-07-15 19:42:03", "subject": "Prueba de nueva conversación 13/07", "status": "NEW", "rating": 0, "last_updated": null, "message_counter": 0, "main_tag": "5", "secondary_tag": null }

Parameter Description
id id for the conversation
client_id client identification
creation_date Date of creation (current date)
subject subject of the conversation
status when we create a new converstion the status is always NEW
rating always 0
last_updated when we create a new converstion the last_update is always null
message_counter when we create a new converstion the message_counter is always 0
main_tag when we create a new converstion the main_tag is always 5
secondary_tag when we create a new converstion the secondary_tag is always null

Get Conversation

Gets conversations of one client

HTTP Request

GET /api/v0/conversations

URL parameters

Parameter Mandatory Description
client_id Yes Client id who creates the conversation
status Yes OPEN: get all the active conversations with status different than CLOSED
CLOSED: get all closed conversations

Response

Response is a JSON with all the conversations in a array:

[ { "id": 72, "client_id": 27694, "creation_date": "2017-11-27 12:44:36", "subject": "DOG SITTING", "status": "USER_PENDING", "rating": 0, "last_updated": "2017-11-28 13:58:36", "message_counter": 12, "main_tag": "14", "secondary_tag": null }, { "id": 73, "client_id": 27694, "creation_date": "2017-11-27 12:45:59", "subject": "IDEAS FOR A GIFT", "status": "SYSTEM_PENDING", "rating": 0, "last_updated": "2017-11-28 18:43:52", "message_counter": 11, "main_tag": "21", "secondary_tag": "254" },

]

Parameters are all the same than getConversation

Parameter Description
id id of the conversation
client_id client identification
creation_date Date of creation
subject subject of the conversation
status status of the conversation
rating ¿?
last_updated date of the last modification
message_counter number of messages inside the conversation
main_tag main tag
secondary_tag secondary tag

Update Conversation

Update a conversations of one client, only these parameters can bu updated:

HTTP Request

PUT /api/v0/conversations

Body parameters in a JSON

Parameter Mandatory Description
id Yes conversation identification
subject No New subject
status No New status of the converation
rating No New rating

{ "id": 83771, "subject": "pepe 22", "status": "CLOSE", "rating": 0, }

Response

Response is a JSON with all the conversations in a array:

Messages

Enables messages with jobbers.

New Message

Creates a new message in a conversation

HTTP Request

POST /api/v0/conversations/{id_conversation}/messages

URL parameters

Parameter Mandatory Description
id_conversation Yes Conversation identification

Body parameters in a JSON

Parameter Mandatory Description
type Yes 'text'
content Yes text inside the message
sender Yes 'client' or 'agent'

{ "type" : "text", "content": "Message text example", "sender": "agent" }

Response

Response is a JSON with all the parameters:

Parameter Description
id message identification
receive  timestamp
type text or attachment
content content of the message

{ "id": "60f5950e0809aa00d3d27899", "received": "2021-07-19 17:06:54", "author_type": "business", "type": "text", "content": "Segunda prueba para ver el identificador que nos da" }

New Attachment

Uploads a file and gets its url

HTTP Request

POST /api/v0/conversations/{id_conversation}/attachments

URL parameters

Parameter Mandatory Description
id_conversation Yes Conversation identification

Body parameters

Parameter Mandatory Description
source Yes file to upload

Response

Response is a JSON with all the parameters:

Parameter Description
mediaUrl  URL to access the file
mediaType mime type of the file

{ "mediaUrl": "https://media.smooch.io/apps/58b34b17b87aed51006a707c/O1jtzdavhi5HTuB5HOy8NZ1l/phpGJfWA4", "mediaType": "application/pdf" }

New Message Attachment

Creates a new message of an attachment in a conversation

HTTP Request

POST /api/v0/conversations/{id_conversation}/messages

URL parameters

Parameter Mandatory Description
id_conversation Yes Conversation identification

Body parameters in a JSON

Parameter Mandatory Description
type Yes 'attachment'
media_url Yes url of the file previously uploaded
sender Yes 'client' or 'agent'

Response

Response is a JSON with all the parameters:

Parameter Description
id  id of the message
received timestamp
author_type 'user' or 'business'
type mime type of the file
media_url url to access the file

{ "id": "60f599c18ad3ec00d34a4a91", "received": "2021-07-19 17:26:57", "author_type": "user", "type": "image/jpeg", "media_url": "https://media.smooch.io/apps/58b34b17b87aed51006a707c/O1jtzdavhi5HTuB5HOy8NZ1l/phpGJfWA4" }

Get Messages

Gets all the messages of a conversation

HTTP Request

GET /api/v0/conversations/{id_conversation}/messages?size=10

URL parameters

Parameter Mandatory Description
id_conversation Yes Conversation identification
size Yes number of messages to reveive

Response

Response is a JSON with an array with all the parameters:

Parameter Description
id  id of the message
received timestamp
author_type 'user' or 'business'
content text of the message if it's a text message
type mime type if it's an aatachment message
media_url url to access the file if it's an attachment message

[ { "id": "60f13158659def00d45198a1", "received": "2021-07-16 09:12:24", "author_type": "business", "content": "Hello :) Bienvenue sur votre assistant personnel.", "type": "text" } ]

Webhooks for Messages

Enables webhooks for messages notifications.

New Webhook

Creates a new webhook for message notifications

HTTP Request

POST /api/v0/webhooks

Body parameters in a JSON

Parameter Mandatory Description
target Yes URL to call with notifications

{ "target" : "http://www.jobbers.com/oneapi/v0/webhooks/callback2" }

Response

Response is a JSON with all the parameters:

Parameter Description
id id of the webhook
url url that will be clled with notifications

{ "id": "149", "url": "http://www.jobbers.com/oneapi/v0/webhooks/callback2" }

Get Webhooks

Get the webhook for message notifications for a enterprise

HTTP Request

GET /api/v0/webhooks

Parameters

There are no parameters, the enterprise id is taken from the token

 Response

Response is a JSON with an array with all the parameters:

Parameter Description
id id of the webhook
url url that will be clled with notifications
enterprise id of the enterprise

[ { "id": "149", "url": "http://www.jobbers.com/oneapi/v0/webhooks/callback2", "enterprise": "280" } ]

Delete Webhook

Delete a webhook with an specified id

HTTP Request

DELETE /api/v0/webhooks/{id_webhook}

URL Parameters

Parameter Mandatory Description
id_webhook Yes webhook identification

Response

Response is a JSON with the id of the webhook

Parameter Description
id id of the webhook

{ "id": "149" }

Boxes Tags

Enables tags management

New Tags

Creates all the new tags

HTTP Request

POST /api/v0/boxes_tags

Body parameters in a JSON

Array of "tags" with these parameters

Parameter Mandatory Description
code Yes code of the tag
description Yes description
technologyType Yes technology

{ "tags" : [ { "code":"2223", "description":"two", "technologyType":"MifareClassicEV1_1K" }, { "code":"2224", "description":"two", "technologyType":"MifareClassicEV1_1K" } ] }

Response

Response is a JSON with result

Parameter Description
data data structure
result result inside the data structure: success or error

{ "data": { "result": "success" } }

Delete Tags

Delete the tags

HTTP Request

DELETE /api/v0/boxes_tags

Body parameters in a JSON

Array of "tags" with the codes

Parameter Mandatory
data data structure
code code of the tags, inside the data structure

{ "tags" : [ { "code":"1111" }, { "code":"2222" } ] }

Response

Response is a JSON with result

Parameter Description
data data structure
result result inside the data structure: success or error

{ "data": { "result": "success" } }

Disconnect Tags

Disconnect the tags

HTTP Request

POST /api/v0/boxes_disconnect_tags

Body parameters in a JSON

Array of "tags" with the codes

Parameter Mandatory
data data structure
code code of the tags, inside the data structure

{ "tags" : [ { "code":"1111" }, { "code":"2222" } ] }

Response

Response is a JSON with result

Parameter Description
data data structure
result result inside the data structure: success or error

{ "data": { "result": "success" } }

Boxes Client Location

Enables client and locations relationships management

New Client Location

Creates a new relationship between a client and a location

HTTP Request

POST /api/v0/boxes_client_location

Body parameters in a JSON

Client and location information

Parameter Mandatory Description
client_id Yes client identification
box_location_uid Yes box identification

{ "client_id" : "12399", "box_location_uid": "2f3cb5c8-7b95-468d-9bb1-715ba9c44d93" }

Response

Response is a JSON with result

Parameter Description
data data structure
result result inside the data structure: success or error

{ "data": { "result": "success" } }

Delete Client Location

Deletes a relationship between a client and a location

HTTP Request

DELETE /api/v0/boxes_client_location

Body parameters in a JSON

Client and location information

Parameter Mandatory Description
client_id Yes client identification
box_location_uid Yes box identification

{ "client_id" : "12399", "box_location_uid": "2f3cb5c8-7b95-468d-9bb1-715ba9c44d93" }

Response

Response is a JSON with result

Parameter Description
data data structure
result result inside the data structure: success or error

{ "data": { "result": "success" } }

Webhooks for Boxes

Enables webhooks for boxes notifications.

New Webhook

Creates a new webhook for box notifications

HTTP Request

POST /api/v0/boxes_webhook

Body parameters in a JSON

Parameter Mandatory Description
target Yes URL to call with notifications

{ "target" : "http://www.jobbers.com/oneapi/v0/webhooks/callback2" }

Response

Response is a JSON with all the parameters:

Parameter Description
id id of the webhook
url url that will be clled with notifications

{ "id": "149", "url": "http://www.jobbers.com/oneapi/v0/webhooks/callback2" }

Get Webhooks

Get the webhook for message notifications for a enterprise

HTTP Request

GET /api/v0/boxes_webhook

Parameters

There are no parameters, the enterprise id is taken from the token

 Response

Response is a JSON with an array with all the parameters:

Parameter Description
data structure
id id of the webhook inside data
url url that will be clled with notifications inside data
enterprise id of the enterprise inside data

{ "data": [ { "id": "150", "url": "http://www.jobbers.com/oneapi/v0/boxes_webhooks/callback2", "enterprise": "280" } ] }

Delete Webhook

Delete a webhook with an specified id

HTTP Request

DELETE /api/v0/boxes_webhook/{id_webhook}

URL Parameters

Parameter Mandatory Description
id_webhook Yes webhook identification

Response

Response is a JSON with the id of the webhook

Parameter Description
id id of the webhook

{ "id": "149" }

PHP