​
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:
  1. Log in to your GetBill account
  2. Navigate to Company → API Client Management
  3. Click Create New Client
  4. Choose the appropriate grant type and scopes for your use case
  5. 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. Choose Your Grant Type

The API supports multiple OAuth 2.0 grant types:
Best for: Server-to-server communication, background jobs, automated systemsThis grant type is ideal when your application needs to access its own resources without user interaction.
curl -X POST https://getbill.io/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:
​
debts:read
string
Read access to debt information
​
debts:write
string
Create, update, and delete debts
​
followups:read
string
Read access to followup information
​
followups:write
string
Create and update followups
​
reports:read
string
Access to reports and analytics
​
company:read
string
Read company profile and statistics
​
users:read
string
Read user information within your company
​
webhooks:read
string
Access webhook logs and statistics

​
Token Response

A successful token request returns: 
{
  "access_token": "xxx.yyy.zzz",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "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"

​
Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get a new access token: 
curl -X POST https://getbill.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

​
Security Best Practices

Secure Storage

Store client secrets and refresh tokens securely. Use environment variables or secure vaults.

HTTPS Only

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

Token Rotation

Implement automatic token refresh 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
  • invalid_grant: Invalid or expired authorization code/refresh token
  • invalid_scope: Requested scope is invalid or not allowed
  • access_denied: User denied authorization

​
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.