Firstlink API Documentation
Base URL
https://api.firstlink.world
Sandbox
https://sandbox.api.firstlink.world
## 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 an `API-TOKEN` header for authentication. Responses are returned in JSON format with appropriate HTTP status codes.
## Table of Contents
- [KYB Search](#kyb-search)
- [List Entities](#list-entities)
- [Retrieve Entity Details](#retrieve-entity-details)
- [List Entity Products](#list-entity-products)
- [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)
- [User](#user)
- [Retrieve User Info](#retrieve-user-info)
- [List My Orders](#list-my-orders)
- [Retrieve My Order](#retrieve-my-order)
- [Teams](#teams)
- [List Orders](#list-orders)
- [Retrieve Order](#retrieve-order)
- [Payments](#payments)
- [Create a Transaction](#create-a-transaction)
- [List Transactions](#list-transactions)
- [Retrieve Transaction](#retrieve-transaction)
- [Retrieve Units Price](#retrieve-units-price)
- [List Invoices](#list-invoices)
- [Retrieve Invoice](#retrieve-invoice)
- [Retrieve Invoice PDF](#retrieve-invoice-pdf)
- [List Unit Packs](#list-unit-packs)
- [Retrieve Unit Pack](#retrieve-unit-pack)
- [List Payment Gateways](#list-payment-gateways)
- [Retrieve Payment Gateway](#retrieve-payment-gateway)
## KYB Search
### List Entities
**Endpoint:** `GET /v1/entities`
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `keyword` (str): Entity's VAT, registration number, etc. or name
- `country` (str): ISO-3 country code (required)
#### Success Response
**200 OK**
```json
{
"count": 6055,
"perPage": 2,
"totalPages": 3028,
"previousPage": null,
"nextPage": "https://api.dev.firstlink.world/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
{
"status": "Unauthorized",
"message": "Please provide a valid API-TOKEN in the headers"
}
```
**400 Bad Request**
```json
{
"message": "Please check your parameters.",
"results": []
}
```
### Retrieve Entity Details
**Endpoint:** `GET /v1/entities/{entityID}`
#### Required
- `API-TOKEN` (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
- `API-TOKEN` (in headers)
- `entityID` (in URL)
#### Success Response
**200 OK**
```json
{
"entityID": "FL1CID70000PKOE",
"message": "Found 2 products for entity CID70000PKOE",
"results": [
{
"productUUID": "9f693fc6-876d-486d-a909-efe11f578b7b",
"productName": "Entity Summary Report",
"productType": "Entity Reports",
"description": "Report with summary data of an entity",
"units": 1,
"price": null,
"currency": null
},
{
"productUUID": "a31c8f69-3a40-44a3-ae85-c362a635d8f6",
"productName": "Entity Overview Report",
"productType": "Entity Reports",
"description": "Report with overview data of an entity",
"units": 2,
"price": null,
"currency": null
}
]
}
```
## AML Check
### Request AML Check
**Endpoint:** `POST /v1/aml-check`
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `name` (str): keyword to search
- `search_type` (str): type of search (one of `broad_search`, `general_search`, `focused_search`, `exact_search`)
- `countries` (list): list of iso31661Alpha2 codes (`/v1/aml-check/resources/countries`)
- `citizenships` (list): list of iso31661Alpha2 codes (`/v1/aml-check/resources/countries`)
- `categories` (list): list of categories names (`/v1/aml-check/resources/categories`)
- `entity_types` (list): list of entity types names (`/v1/aml-check/resources/entity_types`)
#### 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
- `API-TOKEN` (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
- `API-TOKEN` (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
- `API-TOKEN` (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
- `API-TOKEN` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "AML Check price retrieved successfully",
"priceDetails": {
"productUUID": "8c15afc2-40cc-4bd8-adad-3e59f9703a01",
"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
- `API-TOKEN` (in headers)
#### 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",
"uuid": "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 a31c8f69-3a40-44a3-ae85-c362a635d8f6 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
- `API-TOKEN` (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": ""
}
```
## User
### Retrieve User Info
Get user information and current balance
**Endpoint:** `GET /v1/me`
#### Required
- `API-TOKEN` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "User information retrieved successfully",
"user": {
"userUUID": "7a1f3c1b-5752-4d41-9960-b4a90d3654c9",
"username": "admin",
"email": "admin@firstlink.com",
"firstName": "Admin",
"lastName": "Firstlink",
"company": "FirstLink AG",
"balance": {
"availableUnits": 50,
"reservedUnits": 2,
"totalUnits": 52
},
"settings": {
"language": "en",
"timezone": "Europe/Zurich",
"currency": "EUR"
}
}
}
```
### List My Orders
**Endpoint:** `GET /v1/me/orders`
Get all orders for the user (both solo and teams accounts can view them)
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `page` (int): Page number (default: 1)
- `per_page` (int): Items per page (default: 10)
- `date_from` (str, optional): Start date in YYYY-MM-DD format
- `date_to` (str, optional): End date in YYYY-MM-DD format
- `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 on line_item column
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Orders retrieved successfully",
"count": 43,
"perPage": 10,
"totalPages": 5,
"previousPage": null,
"nextPage": "https://api.dev.firstlink.world/v1/orders?page=2&per_page=10",
"orders": [
{
"orderUUID": "77b84bc3-2d28-49dc-bb31-702fb8696a59",
"productUUID": "a31c8f69-3a40-44a3-ae85-c362a635d8f6",
"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
}
]
}
```
### Retrieve My Order
**Endpoint:** `GET /v1/me/orders/{orderUUID}`
Get a specific order for a user (both solo and teams accounts can view them)
#### Required
- `API-TOKEN` (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",
"productUUID": "9f693fc6-876d-486d-a909-efe11f578b7b",
"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
}
}
```
## Teams
### List Orders
**Endpoint:** `GET /v1/orders`
Get all orders for the team (only for teams Account)
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `page` (int): Page number (default: 1)
- `per_page` (int): Items per page (default: 10)
- `date_from` (str, optional): Start date in YYYY-MM-DD format
- `date_to` (str, optional): End date in YYYY-MM-DD format
- `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 on line_item column
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Orders retrieved successfully",
"count": 43,
"perPage": 10,
"totalPages": 5,
"previousPage": null,
"nextPage": "https://api.dev.firstlink.world/v1/orders?page=2&per_page=10",
"orders": [
{
"orderUUID": "77b84bc3-2d28-49dc-bb31-702fb8696a59",
"productUUID": "a31c8f69-3a40-44a3-ae85-c362a635d8f6",
"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
}
]
}
```
### Retrieve Order
**Endpoint:** `GET /v1/orders/{orderUUID}`
Get a specific order from the teams orders (only for teams Account)
#### Required
- `API-TOKEN` (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",
"productUUID": "9f693fc6-876d-486d-a909-efe11f578b7b",
"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
}
}
```
## Payments
### Create a Transaction
**Endpoint:** `POST /v1/me/transactions`
Creates a transaction record with pending status. Transactions can be used to buy unit packs or units.
On the response, it will display information about the transaction and a payment link to proceed with the payment.
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `unit_pack_uuid` (str): unit pack uuid
- `number_of_units` (int): number of units
- `payment_gateway_uuid` (str): payment gateway uuid (optional, default: Stripe)
> **Note:** Either `unit_pack_uuid` OR `number_of_units` must be provided, but not both.
#### Success Response
**201 Created**
```json
{
"status": "success",
"message": "Transaction created successfully. Please proceed with the payment using the provided payment link.",
"transactionDetails": {
"transactionUUID": "d622a606-c37d-4aeb-8c9d-a3eec42dbeb3",
"creationDate": "2025-05-13 10:33:39",
"numberOfUnits": 25,
"purchasePrice": "5.00",
"currency": "USD",
"transactionStatus": "Pending",
"paymentLink": "https://checkout.stripe.com/c/pay/cs_test_a1Wb72j82zm3aj79l2U2aPcxXrD5zX7Bhswz78d92xN15QNufovDaP2dcB#fidkdWxOYHwnPyd1blpxYHZxWjA0VHIxU3FNT3VwdzdJVlJRNG5ubDcwXUpjMGZtYEl8YH1rc1V8cU5MbH9paGpQS1x2UGA2MmhNVXxvQnZOfHY0STFWS0NrQlM2Vk1%2FYUFyT3E9dDZwXHFNNTUwM1dcNzdmNScpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl"
}
}
```
#### Error Responses
**401 Unauthorized** - Wrong API-TOKEN
```json
{
"status": "Unauthorized",
"message": "Please provide a valid API-TOKEN in the headers"
}
```
**400 Bad Request** - Missing required parameters
```json
{
"status": "error",
"message": "Please provide either a unit_pack_uuid OR number_of_units"
}
```
**400 Bad Request** - Invalid unit_pack_uuid format
```json
{
"status": "error",
"message": "unit_pack_uuid must be a UUID"
}
```
**400 Bad Request** - Invalid unit_pack_uuid
```json
{
"status": "error",
"message": "unit_pack_uuid is not valid"
}
```
**400 Bad Request** - Invalid number_of_units format
```json
{
"status": "error",
"message": "number_of_units must be a numeric value"
}
```
**400 Bad Request** - Invalid number_of_units value
```json
{
"status": "error",
"message": "number_of_units must be greater than 0"
}
```
**400 Bad Request** - Invalid payment_gateway_uuid format
```json
{
"status": "error",
"message": "payment_gateway_uuid must be a UUID"
}
```
**400 Bad Request** - Invalid payment_gateway_uuid
```json
{
"status": "error",
"message": "payment_gateway_uuid is not valid"
}
```
### List Transactions
Returns all transactions for a user or teams account
**Endpoint:** `GET /v1/me/transactions`
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `page` (int): Page number (optional, default: 1)
- `per_page` (int): Items per page (optional, default: 10, max: 100)
- `date_from` (str): created_date starting date in YYYY-MM-DD format (optional)
- `date_to` (str): created_date ending date in YYYY-MM-DD format (optional)
- `sort` (str): sort direction for created_at, either 'asc' or 'desc' (optional, default: 'desc')
- `transaction_status` (str): Transaction status (optional)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "User transactions retrieved successfully",
"count": 11,
"perPage": 10,
"totalPages": 2,
"previousPage": null,
"nextPage": "https://api.dev.firstlink.world/me/transactions?page=2&per_page=10",
"transactions": [
{
"transactionUUID": "53518dbc-64ec-415c-8969-836d34b6370a",
"transactionName": "Top Up 5 units",
"creationDate": "2025-04-30T17:06:20.351000",
"numberOfUnits": 5,
"purchasePrice": "5.00",
"currency": "EUR",
"transactionStatus": "Completed",
"username": "admin",
"company": "FirstLink AG",
"paymentReferenceNumber": "12345abcdefg",
"paymentGateway": "Stripe"
}
]
}
```
### Retrieve Transaction
Returns a transaction by UUID
**Endpoint:** `GET /v1/me/transactions/{transactionUUID}`
#### Required
- `API-TOKEN` (in headers)
#### Path Parameters
- `transactionUUID` (str): transaction uuid
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "User transaction retrieved successfully",
"transaction": {
"transactionUUID": "53518dbc-64ec-415c-8969-836d34b6370a",
"transactionName": "Top Up 5 units",
"creationDate": "2025-04-30T17:06:20.351000",
"numberOfUnits": 5,
"purchasePrice": "5.00",
"currency": "EUR",
"transactionStatus": "Completed",
"username": "admin",
"company": "FirstLink AG",
"paymentReferenceNumber": "12345abcdefg",
"paymentGateway": "Stripe"
}
}
```
#### Error Responses
**401 Unauthorized** - Wrong API-TOKEN
```json
{
"status": "Unauthorized",
"message": "Please provide a valid API-TOKEN in the headers"
}
```
**400 Bad Request** - Missing path parameter
```json
{
"status": "error",
"message": "Path parameter is required"
}
```
**400 Bad Request** - Invalid path parameter format
```json
{
"status": "error",
"message": "Path parameter is not a valid UUID"
}
```
### Retrieve Units Price
Get the total purchase price for a specific number of units. The purchase price will be calculated for the user associated to the API Token.
**Endpoint:** `GET /v1/me/units`
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `number_of_units` (int): total number of units (optional, default: 1)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Units retrieved successfully.",
"data": {
"numberOfUnits": 10,
"purchasePrice": "12.50",
"currency": "EUR"
}
}
```
### List Invoices
**Endpoint:** `GET /v1/me/accounts/invoices`
#### Required
- `API-TOKEN` (in headers)
#### Parameters
- `page` (int): Page number (default: 1)
- `per_page` (int): Items per page (default: 10)
- `date_from` (str): invoice creation start date in YYYY-MM-DD format (optional)
- `date_to` (str): invoice creation end date in YYYY-MM-DD format (optional)
- `sort` (str): Sort direction for created_at, either 'asc' or 'desc' (default: 'desc')
- `invoice_status` (str): status of the invoice (optional) (Draft, Void, Deleted, Paid)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "User invoices retrieved successfully",
"count": 31,
"perPage": 10,
"totalPages": 4,
"previousPage": null,
"nextPage": "https://api.dev.firstlink.world/v1/me/accounts/invoices?page=2&per_page=10",
"invoices": [
{
"invoiceUUID": "0bd2fcb9-aadd-44d3-9208-f4c5edd62058",
"invoiceNumber": "2507010000061",
"invoiceDate": "2025-07-23 09:25:22",
"invoiceDueDate": "2025-07-24 09:25:22",
"subTotal": "52.00",
"taxTotal": "4.22",
"total": "56.22",
"currency": "EUR",
"taxType": "VAT",
"taxPercentage": "8.10%",
"invoiceCreationDate": "2025-07-23 09:25:22",
"invoiceUpdateDate": "2025-07-23 09:25:44",
"invoiceStatus": "Paid",
"firstName": "Admin",
"lastName": "Firstlink",
"company": "FirstLink AG",
"billingAddress": {
"businessName": "FirstLink AG",
"addressLine1": "Riedmuehlestrasse 1",
"addressLine2": null,
"addressLine3": null,
"city": "Bruettisellen",
"state": null,
"country": "Switzerland",
"postalCode": "8306",
"email": null,
"taxId": "CHE-109.755.588 MWST"
},
"invoiceItems": [
{
"lineItem": "Buy 104 units",
"netAmount": "52.00",
"taxAmount": "4.22",
"grossAmount": "56.22"
}
]
}
]
}
```
### Retrieve Invoice
**Endpoint:** `GET /v1/me/accounts/invoices/{invoiceUUID}`
#### Required
- `API-TOKEN` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "User invoice retrieved successfully",
"invoice": {
"invoiceUUID": "0bd2fcb9-aadd-44d3-9208-f4c5edd62058",
"invoiceNumber": "2507010000061",
"invoiceDate": "2025-07-23 09:25:22",
"invoiceDueDate": "2025-07-24 09:25:22",
"subTotal": "52.00",
"taxTotal": "4.22",
"total": "56.22",
"currency": "EUR",
"taxType": "VAT",
"taxPercentage": "8.10%",
"invoiceCreationDate": "2025-07-23 09:25:22",
"invoiceUpdateDate": "2025-07-23 09:25:44",
"invoiceStatus": "Paid",
"firstName": "Admin",
"lastName": "Firstlink",
"company": "FirstLink AG",
"billingAddress": {
"businessName": "FirstLink AG",
"addressLine1": "Riedmuehlestrasse 1",
"addressLine2": null,
"addressLine3": null,
"city": "Bruettisellen",
"state": null,
"country": "Switzerland",
"postalCode": "8306",
"email": null,
"taxId": "CHE-109.755.588 MWST"
},
"invoiceItems": [
{
"lineItem": "Buy 104 units",
"netAmount": "52.00",
"taxAmount": "4.22",
"grossAmount": "56.22"
}
]
}
}
```
### Retrieve Invoice PDF
**Endpoint:** `GET /v1/me/accounts/invoices/{invoiceUUID}/download`
#### Required
- `API-TOKEN` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Invoice downloaded successfully",
"invoiceUUID": "0bd2fcb9-aadd-44d3-9208-f4c5edd62058",
"fileType": "pdf",
"data": ""
}
```
### List Unit Packs
Get available unit packs for purchasing
**Endpoint:** `GET /v1/me/unit-packs`
#### Required
- `API-TOKEN` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Unit packs retrieved successfully",
"unitPacks": [
{
"unitPackUUID": "c47f3c1b-5752-4d41-9960-b4a90d3654c9",
"name": "Starter Pack",
"description": "10 units pack",
"numberOfUnits": 10,
"price": "12.50",
"currency": "EUR",
"discountPercentage": "0.00",
"active": true
}
]
}
```
### Retrieve Unit Pack
Returns a unit pack by UUID
**Endpoint:** `GET /v1/unit-packs/{unitPackUUID}`
#### Required
- `API-TOKEN` (in headers)
#### Path Parameters
- `unitPackUUID` (str): unit pack uuid
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Unit packs retrieved successfully",
"unitPack": {
"unitPackUUID": "53518dbc-64ec-415c-8969-836d34b6370a",
"unitPackName": "Enterprise Pack",
"description": "",
"numberOfUnits": 500,
"purchasePrice": "100.00",
"currency": "USD",
"isPopular": true,
"displayOrder": 4
}
}
```
#### Error Responses
**401 Unauthorized** - Wrong API-TOKEN
```json
{
"status": "Unauthorized",
"message": "Please provide a valid API-TOKEN in the headers"
}
```
**400 Bad Request** - Missing path parameter
```json
{
"status": "error",
"message": "Path parameter is required"
}
```
**400 Bad Request** - Invalid path parameter format
```json
{
"status": "error",
"message": "Path parameter is not a valid UUID"
}
```
### List Payment Gateways
Get available payment gateways for transactions
**Endpoint:** `GET /v1/me/payment-gateways`
#### Required
- `API-TOKEN` (in headers)
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Payment gateways retrieved successfully",
"paymentGateways": [
{
"paymentGatewayUUID": "8d7f9e6b-3c52-4a41-8960-b4a90d3654c9",
"name": "Stripe",
"description": "Credit card payments via Stripe",
"gatewayType": "credit_card",
"active": true,
"isDefault": true
}
]
}
```
### Retrieve Payment Gateway
Returns a payment gateway by UUID
**Endpoint:** `GET /v1/payment-gateways/{paymentGatewayUUID}`
#### Required
- `API-TOKEN` (in headers)
#### Path Parameters
- `paymentGatewayUUID` (str): payment gateway uuid
#### Success Response
**200 OK**
```json
{
"status": "success",
"message": "Payment gateways retrieved successfully",
"paymentGateway": {
"paymentGatewayUUID": "53518dbc-64ec-415c-8969-836d34b6370a",
"paymentGatewayName": "Stripe",
"displayOrder": 1
}
}
```
#### Error Responses
**401 Unauthorized** - Wrong API-TOKEN
```json
{
"status": "Unauthorized",
"message": "Please provide a valid API-TOKEN in the headers"
}
```
**400 Bad Request** - Missing path parameter
```json
{
"status": "error",
"message": "Path parameter is required"
}
```
**400 Bad Request** - Invalid path parameter format
```json
{
"status": "error",
"message": "Path parameter is not a valid UUID"
}
```