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
**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.
## 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](#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/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 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
}
]
}
```
### 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
- `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."]
}
}
```
**404 Not Found** – Product not found or not API-available
```json
{
"status": "error",
"message": "Product not found or not available for API."
}
```
**401 Unauthorized**
```json
{
"detail": "Authentication credentials were not provided."
}
```
### 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"
}
]
}
```
#### Error Response
**401 Unauthorized**
```json
{
"detail": "Authentication credentials were not provided."
}
```
## 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
{
"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 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"
}
}
```
## 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 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 Response
**200 OK**
**PDF file type**
```json
{
"status": "success",
"message": "PDF retrieved successfully",
"orderUUID": "9e5674cc5a541fafc980832d2a3efe31",
"recordUUID": null,
"fileType": "pdf",
"data": ""
}
```
**JSON file type**
```json
{
"status": "success",
"message": "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
}
]
}
```