Skip to main content

​
Quick Start Guide

This guide will walk you through making your first API calls to Thredfi.

​
Prerequisites

Before you begin, you need:
  • Partner UUID (provided by Thredfi)
  • API Key (provided by Thredfi)
If you don’t have these credentials, contact [email protected].

​
Authentication Flow

Thredfi uses a two-tier OAuth2 system:
  1. Level 1 (Unscoped): Exchange your credentials for a partner-level token
  2. Level 2 (Scoped): Exchange unscoped token for business-specific tokens
1

Get Unscoped Token

Exchange your partner credentials for an unscoped token:
curl -X POST https://dev-backend.thredfi.com/v1/platform/oauth2/token/ \
  -H "Authorization: Basic $(echo -n 'YOUR_PARTNER_UUID:YOUR_API_KEY' | base64)" \
  -H "Content-Type: application/json"
Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
2

List Your Businesses

Use the unscoped token to list all businesses for your partner:
curl https://dev-backend.thredfi.com/v1/platform/businesses/ \
  -H "Authorization: Bearer YOUR_UNSCOPED_TOKEN"
Response:
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "business-uuid-1",
      "legal_name": "Example Ltd",
      "country": "GB",
      "currency": "GBP",
      "entity_type": "limited",
      "is_active": true
    }
  ]
}
3

Get Business-Scoped Token

Exchange your unscoped token for a business-specific token:
curl -X POST https://dev-backend.thredfi.com/v1/platform/BUSINESS_ID/oauth2/token/ \
  -H "Authorization: Bearer YOUR_UNSCOPED_TOKEN"
Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "business_access"
}
4

Create Your First Invoice

Now use the business-scoped token to create an invoice:
curl -X POST https://dev-backend.thredfi.com/v1/platform/businesses/BUSINESS_ID/invoices/ \
  -H "Authorization: Bearer YOUR_BUSINESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer-uuid",
    "invoice_number": "INV-001",
    "sent_at": "2024-01-15",
    "due_at": "2024-02-15",
    "currency": "GBP",
    "line_items": [
      {
        "description": "Professional Services",
        "quantity": 1,
        "unit_price_cents": 100000,
        "account_code": "4000"
      }
    ]
  }'
Response:
{
  "id": "invoice-uuid",
  "invoice_number": "INV-001",
  "status": "sent",
  "total_amount_cents": 100000,
  "currency": "GBP",
  "created_at": "2024-01-15T10:00:00Z"
}

​
Next Steps

Authentication Guide

Deep dive into our two-tier OAuth2 system

API Reference

Browse all available endpoints

Error Handling

Learn how to handle errors gracefully

Idempotency

Prevent duplicate transactions