Authentication

Overview

The GetBill API uses OAuth 2.0 for authentication. This ensures secure access to your data while allowing you to integrate with third-party applications safely.

Getting Started

1. Create an OAuth Client

First, you need to create an OAuth client in your GetBill dashboard:

Log in to your GetBill account
Navigate to Company → API Client Management
Click Create New Client
Choose the scopes required for your use case
Save your Client ID and Client Secret securely

Admin Access Required: Only company administrators can create and manage OAuth clients. If you don’t see the API Client Management option, contact your company administrator to grant you admin access.

Keep your Client Secret secure and never expose it in client-side code or public repositories.

2. Request an access token

GetBill API clients use the OAuth 2.0 Client Credentials flow. This server-to-server flow does not require user interaction.

curl -X POST https://getbill.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=debts:read debts:write followups:read"

Scopes

Scopes define what your application can access. Request only the scopes you need:

string

Read access to debt information

string

Create, update, and delete debts

string

Upload invoice documents and attach them to debts

string

Read access to followup information

string

Create and update followups

string

Read access to creditor information

string

Create, update, and manage creditors

string

Read access to debtor information

string

Create, update, and manage debtors

string

Read company profile and statistics

string

Read user information within your company

Existing clients may still display reports:read. This deprecated scope remains accepted for authentication compatibility but no longer grants access to report endpoints.

Token Response

A successful token request returns:

{
  "access_token": "xxx.yyy.zzz",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "debts:read debts:write followups:read"
}

Using Access Tokens

Include the access token in the Authorization header for all API requests:

curl -X GET https://getbill.io/external-api/v1/debts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Access token expiration

Access tokens are valid for one hour. When a token expires, request a new one from /oauth/token using the same Client Credentials request.

Security Best Practices

Secure Storage

Store client secrets securely. Use environment variables or secure vaults.

HTTPS Only

Always use HTTPS for all API communications to protect tokens in transit.

Token Renewal

Request a new access token before expiration to avoid service interruptions.

Minimal Scopes

Request only the minimum scopes required for your application functionality.

Error Responses

Authentication errors return standard OAuth 2.0 error responses:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Common error codes:

invalid_client: Invalid client credentials
unsupported_grant_type: Requested grant type is not supported
invalid_scope: Requested scope is invalid or not allowed

Next Steps

Once authenticated, explore these powerful API features:

AI-Powered Workflows

Learn how to use Timeline IDs to automate collection with AI calls, emails, and SMS.

Make Your First Call

Follow our First API Call guide to start integrating.

Testing Authentication

You can test your authentication setup using our API explorer or by making a simple request to the company profile endpoint:

curl -X GET https://getbill.io/external-api/v1/company/profile \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If authentication is successful, you’ll receive your company profile information.

Get started

Guides

SFTP integration

Company API

Creditors API

Debtors API

Debts API

Timelines API

Campaigns API

Settings API

Invoice documents API

Followups API

Todos API

Status API

Overview

Getting Started

1. Create an OAuth Client

2. Request an access token

Scopes

Token Response

Using Access Tokens

Access token expiration

Security Best Practices

Secure Storage

HTTPS Only

Token Renewal

Minimal Scopes

Error Responses

Next Steps

AI-Powered Workflows

Make Your First Call

Testing Authentication

​Overview

​Getting Started

​1. Create an OAuth Client

​2. Request an access token

​Scopes

​Token Response

​Using Access Tokens

​Access token expiration

​Security Best Practices

Secure Storage

HTTPS Only

Token Renewal

Minimal Scopes

​Error Responses

​Next Steps

AI-Powered Workflows

Make Your First Call

​Testing Authentication

Overview

Getting Started

1. Create an OAuth Client

2. Request an access token

Scopes

Token Response

Using Access Tokens

Access token expiration

Security Best Practices

Error Responses

Next Steps

Testing Authentication