Contractors (Public API)

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.

The contractor model

• id — Bob! Desk contractor id
• name — company name (falls back to first/last name)
• siret — 14-digit SIRET, or null
• siren — 9-digit SIREN derived from the SIRET, or null
• email — contact email
• phone — contact phone
• is_internal — true for an internal team, false for an external supplier
• is_active — whether the contractor is active

The detailed view (retrieve by SIREN/SIRET) adds:

• fix — landline number
• address — postal address
• description — free-text description
• currency — ISO currency code (e.g. EUR)
• created_at / updated_at — ISO 8601 dates

List contractors

GET /api/v3.0/contractors

Returns the contractors owned by your account or linked to it as a partner.

Optional query parameters

• active — true | false, filter on is_active
• siret — exact match on the 14-digit SIRET
• cursor — id of the last item of the previous page
• limit — page size, 1..200 (default 50)

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

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

To paginate, pass the id of the last item in 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.

Retrieve a contractor

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

The path parameter 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.

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

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

Returns { "contractor": { ... } }, or 404 if no contractor matches the id/SIREN/SIRET for your account.