Contractors

Read the contractors (suppliers) linked to your account. This resource is meant to help accounting providers (Yooz, etc.) reconcile an invoice supplier.siret with the matching Bob! Desk contractor. Read-only.

Properties

Name
id
Type
string
Description
Unique identifier for the contractor.
Name
name
Type
string
Description
Company name (falls back to first/last name).
Name
siret
Type
string
Description
14-digit SIRET, or null.
Name
siren
Type
string
Description
9-digit SIREN derived from the SIRET, or null.
Name
email
Type
string
Description
Contact email.
Name
phone
Type
string
Description
Contact phone.
Name
is_internal
Type
boolean
Description
true for an internal team, false for an external supplier.
Name
is_active
Type
boolean
Description
Whether the contractor is active.

The detailed view (retrieve by id/SIREN/SIRET) also returns:

Name
fix
Type
string
Description
Landline number.
Name
address
Type
string
Description
Postal address.
Name
description
Type
string
Description
Free-text description.
Name
currency
Type
string
Description
ISO currency code (e.g. EUR).
Name
created_at
Type
string => ISODate
Description
Date when the contractor was created.
Name
updated_at
Type
string => ISODate
Description
Date when the contractor was last updated.

GET/api/v3.0/contractors

Contractors list

This endpoint returns the contractors owned by your account or linked to it as a partner. To paginate, pass the id of the last item of the current page as the cursor parameter of the next request. When the response returns an empty contractors array and cursor is null, you have reached the end of the list.

Optional parameters

Name
active
Type
boolean
Description
true | false, filter on is_active.
Name
siret
Type
string
Description
Exact match on the 14-digit SIRET.
Name
cursor
Type
string
Description
Cursor to paginate the results (id of the last item of the previous page).
Name
limit
Type
number
Description
Page size, 1..200 (default 50).

Request

GET

/api/v3.0/contractors

curl -G https://api.bob-desk.com/api/v3.0/contractors \
  -H "Authorization: Bearer {token}" \
  -d active="true" \
  -d limit="50"

Response

{
  "cursor": "5d973899ecb060003525ddec",
  "contractors": [
    {
      "id": "5d973899ecb060003525ddec",
      "name": "Domo-Elec",
      "siret": "80101747600020",
      "siren": "801017476",
      "email": "contact@domo-elecparis.com",
      "phone": "+33698888576",
      "is_internal": false,
      "is_active": true
    }
  ]
}

GET/api/v3.0/contractors/:id

Retrieve a contractor

This endpoint allows you to retrieve a single contractor. Returns 404 if no contractor matches the id/SIREN/SIRET for your account.

Route parameters

Name
id
Type
string
Description
Accepts any of three identifiers, so you can resolve a contractor straight from an invoice supplier_id, or from a supplier SIREN/SIRET:
- Bob! Desk id (24-char hex) — exact match on the contractor id (e.g. the supplier_id returned by the invoices resource)
- SIRET (14 digits) — exact match
- SIREN (9 digits) — matches the contractor whose SIRET starts with that SIREN
Any other format returns 404.

Request

GET

/api/v3.0/contractors/:id

# by SIREN
curl https://api.bob-desk.com/api/v3.0/contractors/801017476 \
  -H "Authorization: Bearer {token}"

# by Bob! Desk id (e.g. an invoice supplier_id)
curl https://api.bob-desk.com/api/v3.0/contractors/5d973899ecb060003525ddec \
  -H "Authorization: Bearer {token}"

Response

{
  "contractor": {
    "id": "5d973899ecb060003525ddec",
    "name": "Domo-Elec",
    "siret": "80101747600020",
    "siren": "801017476",
    "email": "contact@domo-elecparis.com",
    "phone": "+33698888576",
    "is_internal": false,
    "is_active": true,
    "fix": null,
    "address": "10 rue de Paris, 75011 Paris",
    "description": "Excellente entreprise en electricité",
    "currency": "EUR",
    "created_at": "2020-05-12T20:39:26.433Z",
    "updated_at": "2021-03-10T19:43:09.739Z"
  }
}