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) and AML (Anti-Money Laundering) verification capabilities directly into your applications.
### Core Services
**Business Verification (KYB)**
Search and retrieve detailed information about business entities across multiple jurisdictions. Access registration details, legal status, ownership information, and compliance data to verify business legitimacy and assess risk.
**AML Compliance Checks**
Perform comprehensive anti-money laundering checks with access to global watchlists, sanctions databases, and risk assessment tools. 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.
## Table of Contents
- [Authentication](#authentication)
- [Obtain JWT Token](#obtain-jwt-token)
- [Refresh JWT Token](#refresh-jwt-token)
- [KYB Search](#kyb-search)
- [List Entities](#list-entities)
- [Retrieve Entity Details](#retrieve-entity-details)
- [List Entity Products](#list-entity-products)
- [List Countries (KYB)](#list-countries-kyb)
- [AML Check](#aml-check)
- [Request AML Check](#request-aml-check)
- [List Countries](#list-countries)
- [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. The tokens include tenant information in the payload.
#### 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"
}
```
**400 Bad Request** - 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..."
}
```
#### Error Responses
**401 Unauthorized**
```json
{
"detail": "Token is invalid or expired"
}
```
## KYB Search
### 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 Response
**200 OK**
```json
{
"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",
"businessName": null,
"country": "United States of America",
"county": "Michigan",
"city": null,
"status": "dissolved",
"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",
"businessName": null,
"country": "United States of America",
"county": "Michigan",
"city": null,
"status": "dissolved",
"type": "Limited Liability Company",
"registrationNumber": {
"value": "******940261",
"description": "United States Entity Registry of Michigan"
},
"vatNumber": null,
"idkey1": null,
"idkey2": null,
"idkey3": null,
"idkey4": null
}
]
}
```
#### Error Responses
**401 Unauthorized**
```json
{
"detail": "Authentication credentials were not provided."
}
```
**400 Bad Request**
```json
{
"message": "Please check your parameters.",
"results": []
}
```
### Retrieve Entity Details
**Endpoint:** `GET /v1/entities/{entityID}`
#### Required
- `Authorization: Bearer ` (in headers)
- `entityID` (in URL)
#### Success Response
**200 OK**
```json
{
"message": "Entity details retrieved successfully",
"result": {
"entityID": "FL1CID70004XNP0",
"name": "PT Anugerah Kalimantan Energi",
"businessName": null,
"country": "Indonesia",
"county": null,
"city": "Kota Banjarbaru",
"postalCode": null,
"addressLines": [
"JL. BATAS KOTA DALAM NO. 109, RT 005, RW 002",
"SUNGAI ULIN"
],
"status": "active",
"type": "Limited Company",
"registrationNumber": null,
"vatNumber": null,
"idkey1": {
"value": "****65590",
"description": "Indonesian AHU Data-Id"
},
"idkey2": null,
"idkey3": null,
"idkey4": null
}
}
```
#### Error Response
**400 Bad Request**
```json
{
"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
{
"entityID": "FL1CID70000PKOE",
"message": "Found 2 products for entity CID70000PKOE",
"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
}
]
}
```
### List Countries (KYB)
Get the list of countries available for KYB 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"
}
]
}
```
#### Error Response
**401 Unauthorized**
```json
{
"detail": "Authentication credentials were not provided."
}
```
## AML Check
### Request AML Check
**Endpoint:** `POST /v1/aml-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/aml-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/aml-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/aml-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/aml-check/resources/entity-types`) [`Individual`,`Entity`,`Vessel`,`Aircraft`,`Location`,`Media`,`Security`]
- `customer_reference` (str): Customer order reference (optional)
#### Success Response
**200 OK**
```json
{
"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"
}
]
}
}
```
### List Countries
Get the list of countries from the AML Check Country table
**Endpoint:** `GET /v1/aml-check/resources/countries`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "AML Check 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 from the AML Check Entity Type table
**Endpoint:** `GET /v1/aml-check/resources/entity-types`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "AML Check 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 from the AML Check Category table
**Endpoint:** `GET /v1/aml-check/resources/categories`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "AML Check 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 AML Check request
**Endpoint:** `GET /v1/aml-check/price`
#### Required
- `Authorization: Bearer ` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "AML Check price retrieved successfully",
"priceDetails": {
"productUUID": "44515ed7-0f41-43bd-a852-5917e4cd872c",
"productName": "AML Compliance Check",
"description": "Results of an AML compliance check",
"units": 4,
"price": "2.00",
"currency": "EUR"
}
}
```
## Order
### 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 (required)
- `product_uuid` (str): UUID of FirstLink product (required)
- `customer_reference` (str): Customer order reference (optional)
#### Success Response
**200 OK**
```json
{
"entityID": "CID70004XNP0",
"orderUUID": "2691b548-ec3a-41fc-a9eb-4d56f0b9b8eb",
"status": "Processing",
"message": "Order created successfully"
}
```
#### Error Responses
**400 Bad Request** - Request for non existing entity
```json
{
"status": "Error",
"message": "Entity not found: CID70004XNP01"
}
```
**400 Bad Request** - Request with wrong parameters
```json
{
"status": "Error",
"message": "Please check your parameters."
}
```
**503 Service Unavailable** - Request for a non existing product
```json
{
"status": "Not available",
"message": "Product not found: 9f693fc6-876d-486d-a9f09-efe11f578b7b. Please provide a valid product UUID."
}
```
**503 Service Unavailable** - Request for a product with 1 variant and blocked country
```json
{
"status": "Not available",
"message": "Product 68c5ebb5-2ac3-448a-87f6-48e9b69a2732 is not available. Please contact us for more information."
}
```
**503 Service Unavailable** - Request with an entity with insufficient data for suppliers
```json
{
"status": "Not available",
"message": "Entity does not have sufficient data for supplier"
}
```
**500 Internal Server Error** - Request with an error response from data supplier
```json
{
"status": "Error",
"message": "Failed to process order with supplier. Please contact us for more information."
}
```
**500 Internal Server Error** - Request with an unexpected error
```json
{
"status": "Error",
"message": "Internal server error while creating order. Please contact us for more information."
}
```
### Download
Allows you to download an order report. Works for both AML and KYB orders. For KYB 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 AML records in a response
- `file_type` (str, optional, default: pdf): [json, pdf, …]
> **Note:** For AML 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 AML Check results for that order_uuid, the response will only contain that record.
#### Success Response
**200 OK**
**PDF file type**
```json
{
"status": "success",
"message": "AML Check PDF retrieved successfully",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "pdf",
"data": ""
}
```
**JSON file type**
```json
{
"status": "success",
"message": "AML Check JSON retrieved successfully",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "json",
"data": ""
}
```
### 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
#### 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": "CMT7004PCJ4M",
"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": "CPR2005CMOJP",
"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
}
]
}
```
## 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": "CPR2005CMOJP",
"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
}
]
}
```