GET
/
external-api
/
v1
/
creditors
List Creditors
curl --request GET \
  --url https://getbill.io/external-api/v1/creditors \
  --header 'Authorization: <authorization>'
{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "name": "Acme Corporation",
      "email": "billing@acmecorp.com",
      "phone": "+33142123456",
      "address": "123 Business Street",
      "city": "Paris",
      "postalCode": "75001",
      "country": "France",
      "registrationNumber": "B123456789",
      "taxNumber": "FR12345678901",
      "contactPerson": "John Billing",
      "createdAt": "2024-01-15 10:30:00",
      "updatedAt": "2024-01-20 14:22:00"
    },
    {
      "id": "xyz789ghi012",
      "name": "Services Plus SARL",
      "email": "contact@servicesplus.fr",
      "phone": "+33472987654",
      "address": "456 Avenue des Services",
      "city": "Lyon",
      "postalCode": "69001",
      "country": "France",
      "registrationNumber": "B987654321",
      "taxNumber": "FR98765432109",
      "contactPerson": "Marie Finance",
      "createdAt": "2024-01-10 09:15:00",
      "updatedAt": "2024-01-18 11:45:00"
    }
  ],
  "pagination": {
    "total": 128,
    "page": 1,
    "limit": 50,
    "pages": 3
  }
}

​
Overview

This endpoint returns a paginated list of creditors belonging to the authenticated company. Creditors are entities (companies or organizations) that issue debts and have debtors owing them money.

​
Authentication

Requires a valid OAuth 2.0 access token with the creditors:read scope.

​
Request

​
Authorization
string
required
Bearer token for authentication

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (starts at 1)
​
limit
integer
default:"20"
Number of items per page (maximum 100)

​
Example Request

curl -X GET "/external-api/v1/creditors?page=1&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

​
Response

​
error
boolean
Always false for successful requests
​
data
array
Array of creditor objects
​
pagination
object
Pagination metadata

​
Success Response

{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "name": "Acme Corporation",
      "email": "billing@acmecorp.com",
      "phone": "+33142123456",
      "address": "123 Business Street",
      "city": "Paris",
      "postalCode": "75001",
      "country": "France",
      "registrationNumber": "B123456789",
      "taxNumber": "FR12345678901",
      "contactPerson": "John Billing",
      "createdAt": "2024-01-15 10:30:00",
      "updatedAt": "2024-01-20 14:22:00"
    },
    {
      "id": "xyz789ghi012",
      "name": "Services Plus SARL",
      "email": "contact@servicesplus.fr",
      "phone": "+33472987654",
      "address": "456 Avenue des Services",
      "city": "Lyon",
      "postalCode": "69001",
      "country": "France",
      "registrationNumber": "B987654321",
      "taxNumber": "FR98765432109",
      "contactPerson": "Marie Finance",
      "createdAt": "2024-01-10 09:15:00",
      "updatedAt": "2024-01-18 11:45:00"
    }
  ],
  "pagination": {
    "total": 128,
    "page": 1,
    "limit": 50,
    "pages": 3
  }
}

​
Error Responses

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}

​
Rate Limiting

This endpoint is subject to rate limiting. See the Rate Limits documentation for details. Rate Limit: 1,000 requests per hour