Custobar API Documentation

Appearance

Custobar API ​

Custobar APIs for importing and exporting data

Authentication ​

All API requests require authentication using an API key. The authentication process involves two steps:

  1. Create an Integration - First, create an integration to represent your application or service
  2. Generate an API Key - Then, create an API key for that integration with specific scopes

Once you have an API key, include it in the Authorization header as a Bearer token:

bash
Authorization: Bearer YOUR_API_KEY

Step 1: Create an Integration ​

Create an integration to get started:

bash
curl -X POST "{{ safeSpec.servers[0].url }}/integrations/" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_name": "",
    "parameters": {
      "name": "My Application",
      "description": "Integration for my app"
    }
  }'

This returns an integration object with an id that you'll use in the next step:

json
{
  "integration": {
    "id": "4ii6go3zs2tg",
    "name": "My Application",
    "enabled": true,
    "created_at": "2026-01-09T20:26:35.062554Z",
    ...
  }
}

Step 2: Create an API Key ​

Use the integration ID to create an API key with specific scopes:

bash
curl -X POST "{{ safeSpec.servers[0].url }}/access-tokens/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data imports",
    "owner_id": "integrations/4ii6go3zs2tg",
    "scopes": [
      {"method": "GET", "path": "/api/data/customers/"},
      {"method": "POST", "path": "/api/customers/upload/"}
    ],
    "transfer_privileges": true
  }'

The response includes your API key in the token field. Save it now - you won't be able to retrieve it later:

json
{
  "access_token": {
    "id": "gw44n2x2nlqu",
    "name": "Data imports",
    "token": "APICODEXU5SLHM3ZFHYCXW4FSLY2D7Y2RHO3RYPP",
    "hint": "API***YPP",
    "scopes": [
      {"method": "GET", "path": "/api/data/customers/"},
      {"method": "POST", "path": "/api/customers/upload/"}
    ],
    ...
  }
}

TIP

You can also create and manage API keys through the Custobar web interface.

Getting Started ​

Making Your First Request ​

Here's a simple example to fetch customer data using your API key:

bash
curl -X GET "{{ safeSpec.servers[0].url }}/api/data/customers/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Format ​

All responses are returned in JSON format (unless otherwise specified):

json
{
  "customers": [
    {
      "external_id": "CUSTOMER123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "can_email": true
    }
  ]
}

Available Endpoints ​

Error Handling ​

The API uses standard HTTP status codes:

Status CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters or request body
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end

Error Response Format ​

Error responses include a descriptive message:

json
{
  "error": {
    "code": "invalid_request",
    "message": "The external_id field is required"
  }
}

Rate Limits ​

Rate Limiting

API requests may be subject to rate limiting. If you receive a 429 status code, implement exponential backoff and retry your request after a delay.

Best Practices ​

  1. Use pagination - When fetching large datasets, use the limit parameter and handle paging appropriately
  2. Batch operations - Group multiple records in a single import request when possible
  3. Handle errors gracefully - Always check response status codes and implement proper error handling
  4. Store API keys securely - Never expose API keys in client-side code or public repositories
  5. Validate data - Ensure data conforms to the required schema before importing to avoid validation errors
  6. Use appropriate timeouts - Set reasonable connection and read timeouts for API requests

Data Formats ​

Date and Time ​

  • All timestamps are in ISO 8601 format: 2024-01-15T10:30:00Z
  • Dates should be provided in YYYY-MM-DD format

Boolean Values ​

  • Use true or false (lowercase)

Arrays ​

  • Empty arrays are represented as []
  • Arrays should contain objects of the same type

Additional Resources ​

Need Help?

Explore the sidebar for detailed endpoint documentation, or refer to our comprehensive guides for common integration scenarios.