FirstLink API Documentation
Base URL
https://portal.firstlink.world/api
Sandbox
https://portal.firstlink.world/sandbox
## API Overview
The FirstLink API provides comprehensive business verification and compliance services through a RESTful interface. This API enables you to integrate KYB (Know Your Business) / AML (Anti-Money Laundering) and PEPs/Sanctions verification capabilities directly into your applications.
### Core Services
**Know Your Business (KYB) / Anti-Money Laundering (AML)**
Search and retrieve detailed timely information about business entities across multiple jurisdictions. Access registration details, legal status, ownership information, and compliance data to verify the legitimacy of any business globally, assess the resilience risk and financial crime/Ultimate Beneficial Owner (UBO) discovery. Access to a range of ‘as filed’ official registry documents internationally is also available.
**PEPs, Sanctions and Adverse Media**
Perform comprehensive anti-money laundering checks on Individuals (Directors, Shareholders, UBOs), and Businesses. Also, search on Vessels or Aircraft. With access to global watchlists of PEPs, Sanctions and Adverse Media databases. Support regulatory compliance with automated due diligence workflows.
**User Management & Billing**
Manage user accounts, track usage, handle billing through unit-based pricing, and access detailed transaction history and invoice management.
### Key Features
- **Global Coverage**: Access business data from multiple countries and jurisdictions
- **Real-time Verification**: Instant results for business searches and compliance checks
- **Flexible Pricing**: Unit-based system with transparent pricing for different services
- **Comprehensive Data**: Detailed entity information including registration numbers, VAT numbers, and legal status
- **API-First Design**: RESTful endpoints with JSON responses for easy integration
- **Secure Authentication**: Token-based authentication for secure API access
### Getting Started
To use the FirstLink API, you'll need:
1. An API token for authentication
2. Understanding of the unit-based pricing system
3. Familiarity with the available endpoints and their parameters
All API requests require authentication using JWT tokens. Obtain a JWT token using the authentication endpoints, then include it in the `Authorization: Bearer ` header for subsequent requests. Responses are returned in JSON format with appropriate HTTP status codes.
> **Note:** API token authentication is only available for organizations with POSTPAID billing type.
> **Note:** Every endpoint is either a `GET` or a `POST`. Any other method — `PUT`, `PATCH`,
> `DELETE` — returns **405 Method Not Allowed**. Paths are written without a trailing slash and
> should be sent that way.
Most error responses carry a `status` and a `message`:
```json
{
"status": "error",
"message": "A description of what went wrong"
}
```
As a rule of thumb, **4xx** means the request needs changing, and **5xx** means it does not — either
something failed on our side, or the product you asked for is not configured for your account, in
which case retrying will not help and you should contact us.
#### Common Error Responses
These two can come back from any endpoint, so they are documented here instead of being repeated
under each one.
**401 Unauthorized** - the token is missing, invalid or expired
```json
{
"detail": "Authentication credentials were not provided."
}
```
A rejected token also carries a machine-readable `code` (for example `token_not_valid`), so you can
branch on it rather than on the prose. Get a new one with
[Obtain JWT Token](#obtain-jwt-token).
**500 Internal Server Error** - the request reached us but could not be completed.
```json
{
"status": "error",
"message": "An error occurred while processing the request. Please contact us for more information."
}
```
## Table of Contents
- [Authentication](#authentication)
- [Obtain JWT Token](#obtain-jwt-token)
- [Refresh JWT Token](#refresh-jwt-token)
- [KYB/AML](#kybaml)
- [List Entities](#list-entities)
- [Retrieve Entity Details](#retrieve-entity-details)
- [List Entity Products](#list-entity-products)
- [Request Entity](#request-entity)
- [List Countries (KYB/AML)](#list-countries-kybaml)
- [PEPs/Sanctions](#pepssanctions)
- [Request PEPs/Sanctions](#request-pepssanctions)
- [List Countries (PEPs/Sanctions)](#list-countries-pepssanctions)
- [List Entity Types](#list-entity-types)
- [List Categories](#list-categories)
- [Retrieve Price](#retrieve-price)
- [Order](#order)
- [Request Order](#request-order)
- [Download](#download)
- [Retrieve Order](#retrieve-order)
- [User](#user)
- [Retrieve User Info](#retrieve-user-info)
- [List My Orders](#list-my-orders)
- [Teams](#teams)
- [List Orders](#list-orders)
## Authentication
### Obtain JWT Token
**Endpoint:** `POST /auth/token/`
Obtain JWT access and refresh tokens for API authentication.
#### Body Parameters
- `username` (str): User username (required)
- `password` (str): User password (required)
#### Success Response
**200 OK**
```json
{
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"username": "admin"
}
```
The `access` token should be included in the `Authorization: Bearer ` header for all subsequent API requests. The `refresh` token can be used to obtain a new access token when it expires.
#### Error Responses
**401 Unauthorized**
```json
{
"detail": "No active account found with the given credentials"
}
```
**401 Unauthorized** - Organization billing type validation
```json
{
"detail": "API token authentication is only available for POSTPAID organizations."
}
```
### Refresh JWT Token
**Endpoint:** `POST /auth/token/refresh/`
Refresh an expired access token using a valid refresh token.
#### Body Parameters
- `refresh` (str): Valid refresh token (required)
#### Success Response
**200 OK**
```json
{
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
}
```
#### Error Responses
**401 Unauthorized**
```json
{
"detail": "Token is invalid or expired"
}
```
**400 Bad Request** - `refresh` missing from the request body
```json
{
"refresh": [
"This field is required."
]
}
```
## KYB/AML
### List Entities
**Endpoint:** `GET /v1/entities`
#### Required
- `Authorization: Bearer ` (in headers)
#### Parameters
- `keyword` (str): Entity's VAT, registration number, etc. or name
- `country` (str): ISO-3 country code (required)
- `page` (int): results page offset
- `per_page`(int): amount of results per page
#### Success Responses
**200 OK**
```json
{
"status": "success",
"count": 6055,
"perPage": 2,
"totalPages": 3028,
"previousPage": null,
"nextPage": "https://portal.firstlink.world/api/entities?country=USA&keyword=COMPANY&page=2&per_page=2",
"message": "\n Found 6055 results for:\n Keyword: COMPANY\n Country: USA\n\n Note: If more than 20 results are found, please refine your search or provide page number.\n ",
"results": [
{
"entityID": "FL1CUS500493JGL",
"name": "CO-004, LLC",
"country": "United States of America",
"county": "Michigan",
"city": null,
"type": "Limited Liability Company",
"registrationNumber": {
"value": "******940249",
"description": "United States Entity Registry of Michigan"
},
"vatNumber": null,
"idkey1": null,
"idkey2": null,
"idkey3": null,
"idkey4": null
},
{
"entityID": "FL1CUS70047BY6V",
"name": "CO-003, LLC",
"country": "United States of America",
"county": "Michigan",
"city": null,
"type": "Limited Liability Company",
"registrationNumber": {
"value": "******940261",
"description": "United States Entity Registry of Michigan"
},
"vatNumber": null,
"idkey1": null,
"idkey2": null,
"idkey3": null,
"idkey4": null
}
]
}
```
**200 OK** - the keyword is too short to narrow the search, so no results are returned
```json
{
"status": "success",
"count": 0,
"perPage": 20,
"totalPages": 0,
"previousPage": null,
"nextPage": null,
"message": "Please provide a keyword with at least 3 characters (too many results)",
"results": []
}
```
#### Error Responses
**400 Bad Request**
```json
{
"status": "error",
"message": "Please check your parameters.",
"results": []
}
```
**400 Bad Request** - `country` is not a valid ISO-3 code
```json
{
"status": "error",
"message": "Country XXX is not valid. Should be a valid ISO3 code.",
"results": []
}
```
### Retrieve Entity Details
**Endpoint:** `GET /v1/entities/{entityID}`
#### Required
- `Authorization: Bearer ` (in headers)
- `entityID` (in URL)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Entity details retrieved successfully",
"result": {
"entityID": "FL1CID70004XNP0",
"name": "PT Anugerah Kalimantan Energi",
"country": "Indonesia",
"county": null,
"city": "Kota Banjarbaru",
"postalCode": null,
"addressLines": [
"JL. BATAS KOTA DALAM NO. 109, RT 005, RW 002",
"SUNGAI ULIN"
],
"type": "Limited Company",
"registrationNumber": null,
"vatNumber": null,
"idkey1": {
"value": "****65590",
"description": "Indonesian AHU Data-Id"
},
"idkey2": null,
"idkey3": null,
"idkey4": null
}
}
```
#### Error Responses
**400 Bad Request** - entityID is not provided
```json
{
"status": "error",
"message": "Missing entityID parameter",
"result": null
}
```
**400 Bad Request** — the id does not match the accepted format
```json
{
"status": "error",
"message": "Invalid entityID",
"result": null
}
```
**404 Not Found**
```json
{
"status": "error",
"message": "Entity not found",
"result": null
}
```
### List Entity Products
Returns all available products for an entity
**Endpoint:** `GET /v1/entities/{entityID}/products`
#### Required
- `Authorization: Bearer ` (in headers)
- `entityID` (in URL)
#### Success Response
**200 OK**
```json
{
"status": "success",
"entityID": "FL1CID70000PKOE",
"message": "Found 2 products for entity FL1CID70000PKOE",
"results": [
{
"productUUID": "e212c2f9-2779-4b7b-b6a9-08a1ff60abd9",
"productName": "Entity Summary Report",
"productType": "Entity Reports",
"description": "Report with summary data of an entity",
"units": 1,
"price": null,
"currency": null
},
{
"productUUID": "68c5ebb5-2ac3-448a-87f6-48e9b69a2732",
"productName": "Entity Overview Report",
"productType": "Entity Reports",
"description": "Report with overview data of an entity",
"units": 2,
"price": null,
"currency": null
}
]
}
```
#### Error Responses
**400 Bad Request** - entityID is not provided
```json
{
"status": "error",
"message": "Missing entityID parameter",
"result": null
}
```
**400 Bad Request** — the id does not match the accepted format
```json
{
"status": "error",
"message": "Invalid entityID",
"result": null
}
```
**404 Not Found**
```json
{
"status": "error",
"message": "Entity not found",
"result": null
}
```
**400 Bad Request** - the country encoded in the entity ID is unknown or not active for your account
```json
{
"status": "error",
"message": "Country not found for entity FL1CID70000PKOE or country is not active"
}
```
**503 Service Unavailable** - no products are configured for API ordering on your account. Provider
configuration, so retrying will not help
```json
{
"status": "error",
"message": "Products not available"
}
```
**503 Service Unavailable** - the account is not configured to reach the upstream service
```json
{
"status": "error",
"message": "Service is not available. Please contact us for more information."
}
```
### Request Entity
Request a report for a non-existing entity in a particular product (e.g. Entity Insight, Financial Crime, Resilience Risk, Resilience Review). The product to order is specified by `product_uuid` (e.g. from [List Entity Products](#list-entity-products)).
**Endpoint:** `POST /v1/entities/request`
#### Required
- `Authorization: Bearer ` (in headers)
- `product_uuid` (str): UUID of the product to order (required)
- `name` (str): Entity legal name (required)
- `country_iso3` (str): ISO 3166-1 alpha-3 country code (required)
- `address_line1` (str): Primary address line (required)
- `city` (str): City name (required)
#### Optional Body Parameters
- `jurisdiction` (str): Jurisdiction name. **Conditionally required** — when the chosen product has
jurisdiction-specific variants for `country_iso3`, omitting it is rejected. There is no way to know
in advance from this endpoint; the error names the field when it applies
- `address_line2` (str): Additional address line
- `postal_code` (str): Postal or ZIP code
- `email` (str): Contact email
- `phone_number` (str): Contact phone number
- `notes` (str): Additional comments for the order
- `register_number` (str): Company registration number
- `website` (str): Company website URL
- `customer_reference` (str): Your internal reference for this order
- `id_key` (str): Optional identifier key for the entity
#### Success Response
**201 Created**
```json
{
"orderUUID": "2691b548-ec3a-41fc-a9eb-4d56f0b9b8eb",
"status": "Processing",
"message": "Order created successfully"
}
```
#### Error Responses
**400 Bad Request** – Validation error
```json
{
"status": "error",
"message": "Please check your parameters and try again.",
"errors": {
"country_iso3": ["Invalid country ISO3 code"],
"name": ["This field may not be blank."]
}
}
```
**400 Bad Request** – the `product_uuid` is unavailable, or the product is not sold for
`country_iso3`
```json
{
"status": "error",
"message": "Product not found, not available for API or not available for offline orders."
}
```
**400 Bad Request** - product not available for the country
```json
{
"status": "error",
"message": "Product is not available for the selected country."
}
```
### List Countries (KYB/AML)
Get the list of countries available for KYB/AML searches
**Endpoint:** `GET /v1/entities/countries`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Countries retrieved successfully",
"count": 195,
"countries": [
{
"name": "United States",
"iso2": "US",
"iso3": "USA"
},
{
"name": "United Kingdom",
"iso2": "GB",
"iso3": "GBR"
}
]
}
```
## PEPs/Sanctions
### Request PEPs/Sanctions
**Endpoint:** `POST /v1/ps-check`
#### Required
- `Authorization: Bearer ` (in headers)
#### Body Parameters
- `name` (str): keyword to search (required)
- `search_type` (str): controls how closely a result must match your query before it's returned. Broader searches (`broad_search` or `general_search`) cast a wider net and may include weaker matches, while narrower searches (`focused_search` or `exact_search`) return only strong or exact matches for greater accuracy. Must be one of: `broad_search`, `general_search`, `focused_search`, `exact_search`. If not provided, the API will use its default search behavior.
- `countries` (list): list of iso31661Alpha2 codes.Must be defined in the request body, but can be an empty array. If empty, no filtering by countries will be applied. (`/v1/ps-check/resources/countries`)
- `citizenships` (list): list of iso31661Alpha2 codes. Must be defined in the request body, but can be an empty array. If empty, no filtering by citizenships will be applied. (`/v1/ps-check/resources/countries`)
- `categories` (list): list of categories names. Must be defined in the request body, but can be an empty array. If empty, no filtering by categories will be applied. (`/v1/ps-check/resources/categories`)
- `entity_types` (list): list of entity types names. Must be defined in the request body, but can be an empty array. If empty, no filtering by entity types will be applied. (`/v1/ps-check/resources/entity-types`) [`Individual`,`Entity`,`Vessel`,`Aircraft`,`Location`,`Media`,`Security`]
- `customer_reference` (str): Customer order reference (optional)
#### Success Response
**200 OK**
```json
{
"status": "success",
"orderUUID": "5f5c4caf-af3d-45e6-8234-ea5e0d37700c",
"message": "Found 1 results (limited to 200) for name: Apple",
"results": {
"totalResults": 1,
"results": [
{
"recordNumber": "2507001",
"recordUUID": "953cfcf5-9f19-477d-b007-8630908827c6",
"name": "Pat Apple",
"entityType": "Individual",
"source": "Global PEPs",
"lists": ["United States of America"],
"citizenships": [
{
"country": "United States of America",
"countryCode": "USA"
}
],
"dobs": ["1957-08-31"],
"lowQualityName": false,
"firstName": "Pat",
"lastName": "Apple",
"middleName": null,
"maidenName": null,
"nickName": null,
"nameAliases": [
{
"fullName": "Apple",
"firstName": null,
"lastName": null,
"middleName": null,
"maidenName": null,
"nickName": null,
"lowQualityName": true
},
{
"fullName": "P Apple",
"firstName": null,
"lastName": null,
"middleName": null,
"maidenName": null,
"nickName": null,
"lowQualityName": true
}
],
"pobs": null,
"addresses": [
{
"city": "Louisburg",
"country": "United States of America",
"countryCode": "USA"
}
],
"relationships": [],
"url": null,
"title": null,
"snippet": null,
"article": null,
"additional_info": [
{
"label": "Description",
"values": ["American politician"]
},
{
"label": "Occupation",
"values": ["Politician"]
},
{
"label": "Position Held",
"values": ["member of the State Senate of Kansas"]
}
],
"lastUpdated": "2024-06-14T16:10:26Z"
}
]
}
}
```
#### Error Responses
Validation failures all return **400 Bad Request** with the same shape — a `message` naming the
field at fault and an empty `results` array — so a rejected search is distinguishable from a search
that simply found nothing only by the status code.
**400 Bad Request** - `name` is missing or empty
```json
{
"status": "error",
"message": "Name is required",
"results": []
}
```
**400 Bad Request** - `search_type` is not one of the four accepted values
```json
{
"status": "error",
"message": "Search type should be one of the following types: 'broad_search', 'general_search', 'focused_search' or 'exact_search'",
"results": []
}
```
**400 Bad Request** - a value in `categories` is not recognised
```json
{
"status": "error",
"message": "Category (Politician) is not valid. Empty list will default to all categories.",
"results": []
}
```
**400 Bad Request** - a value in `entity_types` is not recognised
```json
{
"status": "error",
"message": "Entity type is not valid. Please check the entity types endpoint and pass the desired entity types names.",
"results": []
}
```
**400 Bad Request** - a value in `countries` is not a valid ISO 3166-1 alpha-2 code
```json
{
"status": "error",
"message": "Country XYZ is not valid. Please check the countries endpoint and pass the iso31661Alpha2 codes.",
"results": []
}
```
**400 Bad Request** - a value in `citizenships` is not a valid ISO 3166-1 alpha-2 code
```json
{
"status": "error",
"message": "Citizenship XYZ is not valid. Please check the countries endpoint and pass the iso31661Alpha2 codes.",
"results": []
}
```
### List Countries (PEPs/Sanctions)
Get the list of countries for PEPs/Sanctions
**Endpoint:** `GET /v1/ps-check/resources/countries`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Countries retrieved successfully",
"count": 257,
"countries": [
{
"countryUUID": "ac3c239b-ff93-4e35-ba23-747b4e783f00",
"officialName": "Taiwan",
"iso31661Numeric": 158,
"iso31661Alpha2": "TW",
"iso31661Alpha3": "TWN",
"synthetic": false
},
{
"countryUUID": "4a3d0a2a-df58-4fac-9f2f-cca94a541287",
"officialName": "Afghanistan",
"iso31661Numeric": 4,
"iso31661Alpha2": "AF",
"iso31661Alpha3": "AFG",
"synthetic": false
}
]
}
```
### List Entity Types
Get the list of entity types for the PEPs/Sactions
**Endpoint:** `GET /v1/ps-check/resources/entity-types`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Entity Types retrieved successfully",
"count": 7,
"entityTypes": [
{
"entityTypeUUID": "1399ceac-15f0-49c0-a646-0ffe977329ec",
"name": "Individual"
},
{
"entityTypeUUID": "056f0f1f-de62-48c9-8174-830c6530e140",
"name": "Entity"
}
]
}
```
### List Categories
Get the list of categories for the PEPs/Sanctions
**Endpoint:** `GET /v1/ps-check/resources/categories`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Categories retrieved successfully",
"count": 9,
"categories": [
{
"categoryUUID": "10a2dd82-48f7-4209-8499-5ad21e45aa1f",
"name": "Sanctions"
},
{
"categoryUUID": "37618725-6e8a-4cb4-a6be-7253c5996df3",
"name": "PEPs"
}
]
}
```
### Retrieve Price
Get the price for an PEPs/Sanctions request
**Endpoint:** `GET /v1/ps-check/price`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Price retrieved successfully",
"priceDetails": {
"productUUID": "44515ed7-0f41-43bd-a852-5917e4cd872c",
"productName": "PEPs/Sanctions",
"description": "Results of an PEPs/Sanctions check",
"units": 4,
"price": "2.00",
"currency": "EUR"
}
}
```
#### Error Responses
**503 Service Unavailable** - the PEPs/Sanctions product is not configured for API ordering on your
account: absent, not enabled for the API, or with no active price. Provider configuration, so
retrying will not help
```json
{
"status": "error",
"message": "Product is not available. Please contact us for more information."
}
```
## Order
> **Note:** Completed orders are retained for a configurable period. Once a completed order falls
> outside that window it stops appearing in [List Orders](#list-orders) and
> [List My Orders](#list-my-orders), and [Retrieve Order](#retrieve-order) and
> [Download](#download) answer **404** for it — the same response as an order that never existed.
> Retrieve anything you need to keep before then.
### Request Order
**Endpoint:** `POST /v1/orders`
Request an order for a product of an entity.
#### Required
- `Authorization: Bearer ` (in headers)
#### Body Parameters
- `entity_id` (str): Alphanumeric id of an entity, maximum 15 characters (required)
- `product_uuid` (str): UUID of FirstLink product (required)
- `customer_reference` (str): Customer order reference, maximum 255 characters (optional)
#### Success Response
**201 Created**
```json
{
"entityID": "FL1CID70004XNP0",
"entityName": "PT Anugerah Kalimantan Energi",
"orderUUID": "2691b548-ec3a-41fc-a9eb-4d56f0b9b8eb",
"status": "Processing",
"message": "Order created successfully"
}
```
The order is accepted asynchronously and starts as `Processing`. Use
[Retrieve Order](#retrieve-order) to follow it, or configure a webhook to be notified when it
changes.
#### Error Responses
**400 Bad Request** - Request for non existing entity
```json
{
"status": "error",
"message": "Entity not found: FL1CID70004XNP01"
}
```
**400 Bad Request** - Request with wrong parameters
```json
{
"status": "error",
"message": "Please check your parameters and try again."
}
```
**400 Bad Request** - Request for a non existing product
```json
{
"status": "error",
"message": "Product not found: 9f693fc6-876d-486d-a9f09-efe11f578b7b. Please provide a valid product UUID."
}
```
**503 Service Unavailable** - Request for a product that is not orderable for that entity. The request itself was valid; the product is unavailable because of provider configuration, and retrying will not change that
```json
{
"status": "error",
"message": "Product 68c5ebb5-2ac3-448a-87f6-48e9b69a2732 is not available. Please contact us for more information."
}
```
### Download
Allows you to download an order report. Works for both KYB/AML and PEPs/Sanctions orders. For KYB/AML orders, also checks for the status of the order.
**Endpoint:** `GET /v1/download`
#### Required
- `Authorization: Bearer ` (in headers)
#### Parameters
- `order_uuid` (str, required): order.order_uuid
- `record_uuid` (str, optional): record uuid associated with the PEPs/Sanctions records in a response
- `file_type` (str, optional, default: pdf): [json, pdf, …]
> **Note:** For PEPs/Sanctions orders, if the `record_uuid` is not provided, the response will contain all the results. If the `record_uuid` is provided and is part of the PEPs/Sanctions results for that order_uuid, the response will only contain that record.
#### Success Responses
**PDF file type**
**200 OK** - PDF is ready
```json
{
"status": "Completed",
"message": "Report is ready",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "pdf",
"data": "base64_encoded_string"
}
```
**200 OK** - Order still processing
```json
{
"status": "Processing",
"message": "Report is being processed. Please check back later",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "pdf",
"data": ""
}
```
**JSON file type**
**200 OK** - JSON is ready
```json
{
"status": "Completed",
"message": "Report is ready",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "json",
"data": "json_response"
}
```
**200 OK** - Order still processing
```json
{
"status": "Processing",
"message": "Report is being processed. Please check back later",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "json",
"data": {}
}
```
#### Error Responses
**400 Bad Request** - parameters validation errors
```json
{
"status": "error",
"message": "Order UUID is required"
}
```
**403 Forbidden** - the order belongs to another organization
```json
{
"status": "error",
"message": "Access denied"
}
```
**404 Not Found** - no such order, the `order_uuid` is not a valid UUID, or the order is completed and
outside the retention window
```json
{
"status": "error",
"message": "Order not found"
}
```
### Retrieve Order
**Endpoint:** `GET /v1/orders/{orderUUID}`
Get a specific order. Works for both user's own orders and team orders (requires appropriate permissions).
#### Required
- `Authorization: Bearer ` (in headers)
#### Path Parameters
- `orderUUID` (str, required): UUID of the order. A value that is not a valid UUID returns the same
**404** as an unknown one
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Order details retrieved successfully",
"order": {
"orderUUID": "2b9ef8f9-435e-446c-af54-1c6dec1f6d9e",
"orderReference": "ORD-2025-002",
"productUUID": "e212c2f9-2779-4b7b-b6a9-08a1ff60abd9",
"productName": "Entity Summary Report",
"entityID": "FL1CMT7004PCJ4M",
"orderDescription": "CCCLVI Ltd.",
"orderStatus": "Completed",
"units": 1,
"customerReference": null,
"orderCreationDateTime": "2025-06-30T09:46:11.864621",
"orderUpdateDateTime": "2025-06-30T09:46:13",
"orderDeliveryDateTime": null
}
}
```
#### Error Responses
**404 Not Found**
```json
{
"status": "error",
"message": "Order not found"
}
```
**403 Forbidden**
```json
{
"status": "error",
"message": "Access denied"
}
```
## User
### Retrieve User Info
Get user information and current balance
**Endpoint:** `GET /v1/me`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "User information retrieved successfully",
"user": {
"userUUID": "7a1f3c1b-5752-4d41-9960-b4a90d3654c9",
"username": "admin",
"email": "noreply@firstlink.world",
"firstName": "Admin",
"lastName": "FirstLink",
"company": "FirstLink",
"unitsBalance": 50
}
}
```
### List My Orders
**Endpoint:** `GET /v1/me/orders`
Get all orders for the user (both solo and teams accounts can view them)
#### Required
- `Authorization: Bearer ` (in headers)
#### Parameters
- `page` (int): Page number (default: 1)
- `per_page` (int): Items per page (default: 10)
- `sort` (str): Sort direction for created_at, either 'asc' or 'desc' (default: 'desc')
- `order_status` (str, optional): Processing, Completed, Not found, Cancelled, Failed
- `order_description` (str, optional): Description of the order, searches in entity_id, customer_reference, line_item, and organization name
#### Success Response
**200 OK**
> **Note:** The `previousPage` and `nextPage` fields contain page numbers (integers) or `null`, not URLs. Use these values with the `page` parameter for pagination.
```json
{
"status": "success",
"message": "Orders retrieved successfully",
"count": 43,
"perPage": 10,
"totalPages": 5,
"previousPage": null,
"nextPage": 2,
"orders": [
{
"orderUUID": "77b84bc3-2d28-49dc-bb31-702fb8696a59",
"orderReference": "ORD-2025-001",
"productUUID": "68c5ebb5-2ac3-448a-87f6-48e9b69a2732",
"productName": "Entity Overview Report",
"entityID": "FL1CPR2005CMOJP",
"orderDescription": "TEST COMPANY, INC.",
"orderStatus": "Failed",
"units": 2,
"customerReference": null,
"orderCreationDateTime": "2025-06-30T11:34:43.520029",
"orderUpdateDateTime": "2025-06-30T11:34:43",
"orderDeliveryDateTime": null
}
]
}
```
#### Error Responses
**400 Bad Request** - `page` or `per_page` is not a positive integer. A `page` beyond the last one is
*not* an error: it returns the first page
```json
{
"status": "error",
"message": "'page' must be an integer."
}
```
**400 Bad Request** - `page` must be 1 or greater.
```json
{
"status": "error",
"message": "'page' must be 1 or greater.",
}
```
**403 Forbidden** - the account is not permitted to list its own orders
```json
{
"status": "error",
"message": "Access denied"
}
```
## Teams
### List Orders
**Endpoint:** `GET /v1/orders`
Get all orders for the team (only for teams Account)
#### Required
- `Authorization: Bearer ` (in headers)
#### Parameters
- `page` (int): Page number (default: 1)
- `per_page` (int): Items per page (default: 10)
- `sort` (str): Sort direction for created_at, either 'asc' or 'desc' (default: 'desc')
- `order_status` (str, optional): Processing, Completed, Not found, Cancelled, Failed
- `order_description` (str, optional): Description of the order, searches in entity_id, customer_reference, line_item, and organization name
#### Success Response
**200 OK**
> **Note:** The `previousPage` and `nextPage` fields contain page numbers (integers) or `null`, not URLs. Use these values with the `page` parameter for pagination.
```json
{
"status": "success",
"message": "Orders retrieved successfully",
"count": 43,
"perPage": 10,
"totalPages": 5,
"previousPage": null,
"nextPage": 2,
"orders": [
{
"orderUUID": "77b84bc3-2d28-49dc-bb31-702fb8696a59",
"orderReference": "ORD-2025-001",
"productUUID": "68c5ebb5-2ac3-448a-87f6-48e9b69a2732",
"productName": "Entity Overview Report",
"entityID": "FL1CPR2005CMOJP",
"orderDescription": "TEST COMPANY, INC.",
"orderStatus": "Failed",
"units": 2,
"customerReference": null,
"orderCreationDateTime": "2025-06-30T11:34:43.520029",
"orderUpdateDateTime": "2025-06-30T11:34:43",
"orderDeliveryDateTime": null
}
]
}
```
#### Error Responses
**400 Bad Request** - `page` or `per_page` is not a positive integer. A `page` beyond the last one is
*not* an error: it returns the first page
```json
{
"status": "error",
"message": "'page' must be an integer."
}
```
**400 Bad Request** - `page` must be 1 or greater.
```json
{
"status": "error",
"message": "'page' must be 1 or greater.",
}
```
**403 Forbidden** - the user is not permitted to view their organization's orders
```json
{
"status": "error",
"message": "Access denied"
}
```