TravelPass API Documentation
The TravelPass American Samoa API provides programmatic access to traveler declaration data and reference information for integrating with external systems.
Base URL
/api/v1Quick Start
- Obtain an API token from your administrator
- Include the token in the Authorization header
- Make requests to the API endpoints
Test API Connection
curl -X GET "/api/v1/health"Authentication
Protected endpoints require a Bearer token in the Authorization header. API tokens are created by administrators through the admin dashboard.
Authorization Header Format
Authorization: Bearer <your-api-token>Authenticated Request
curl -X GET "/api/v1/declarations" \
-H "Authorization: Bearer your_api_token_here"Token Permissions
API tokens are granted specific permissions that control which endpoints can be accessed:
| Permission | Access |
|---|---|
read:declarations | Access to declaration endpoints |
read:statistics | Access to statistics and reports |
read:reference | Access to reference data (also publicly available) |
Rate Limiting
API requests are rate-limited per token to ensure fair usage and system stability. The default limit is 100 requests per minute.
Rate Limit Headers
All API responses include headers indicating your current rate limit status:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the rate limit resets |
Rate Limit Exceeded
When the rate limit is exceeded, the API returns a 429 status code. Check the Retry-After header for when you can retry.
Endpoints
Health Check
GET
/api/v1/healthCheck the API status and availability. No authentication required.
Response Example
{
"status": "healthy",
"timestamp": "2024-12-17T10:30:00.000Z",
"version": "1.0.0"
}Error Responses
503API is disabled
Declarations
GET
/api/v1/declarationsRequires AuthRetrieve a paginated list of traveler declarations with optional filtering.
Required Permission:
read:declarationsParameters
| Name | Type | Location | Description |
|---|---|---|---|
page | integer | query | Page number (default: 1) |
limit | integer | query | Items per page (default: 20, max: 100) |
status | string | query | Filter by status: draft, submitted |
tripType | string | query | Filter by trip type: arriving_visitor, arriving_resident, departing, transit |
modeOfTravel | string | query | Filter by mode: air, sea |
fromDate | date | query | Filter submissions from date (ISO 8601) |
toDate | date | query | Filter submissions until date (ISO 8601) |
Response Example
{
"data": [
{
"id": "AS-XK7H2M-2024",
"status": "submitted",
"submittedAt": "2024-12-17T08:00:00.000Z",
"tripType": "arriving_visitor",
"modeOfTravel": "air",
"travelerName": "John Doe",
"citizenship": "US",
"arrivalDate": "2024-12-20"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 150,
"totalPages": 8
}
}Error Responses
401Missing or invalid token
403Insufficient permissions
429Rate limit exceeded
GET
/api/v1/declarations/{id}Requires AuthRetrieve a single declaration by its ID with full details.
Required Permission:
read:declarationsParameters
| Name | Type | Location | Description |
|---|---|---|---|
id* | string | path | Declaration ID (e.g., AS-XK7H2M-2024) |
Response Example
{
"data": {
"id": "AS-XK7H2M-2024",
"status": "submitted",
"submittedAt": "2024-12-17T08:00:00.000Z",
"tripType": "arriving_visitor",
"modeOfTravel": "air",
"personalInfo": {
"firstName": "John",
"lastName": "Doe",
"passportNumber": "123456789",
"citizenship": "US",
"dateOfBirth": "1985-03-15",
"gender": "male"
},
"travelDetails": {
"airline": "Hawaiian Airlines",
"flightNumber": "HA123",
"arrivalDate": "2024-12-20"
},
"declarations": {
"agricultureItems": false,
"animals": false,
"currency": false,
"restrictedItems": false
}
}
}Error Responses
401Missing or invalid token
403Insufficient permissions
404Declaration not found
429Rate limit exceeded
Reference Data
Reference data endpoints are publicly accessible and do not require authentication.
GET
/api/v1/referenceList all available reference data types.
Response Example
{
"data": [
{ "type": "countries", "description": "Country list", "count": 195 },
{ "type": "airlines", "description": "Airlines serving AS", "count": 12 },
{ "type": "vessels", "description": "Registered vessels", "count": 45 },
{ "type": "villages", "description": "Villages in AS", "count": 74 },
{ "type": "islands", "description": "Islands in AS", "count": 7 },
{ "type": "purposeOfVisit", "description": "Visit purposes", "count": 8 }
]
}GET
/api/v1/reference/{type}Retrieve reference data for a specific type.
Parameters
| Name | Type | Location | Description |
|---|---|---|---|
type* | string | path | Reference type: countries, airlines, vessels, villages, islands, purposeOfVisit, departurePurposeOfVisit, discoverySource, mainAppeal, placeOfStay, maritalStatus, educationLevels |
Response Example
{
"data": [
{ "id": "us", "name": "United States", "code": "US" },
{ "id": "ws", "name": "Samoa", "code": "WS" },
{ "id": "nz", "name": "New Zealand", "code": "NZ" }
]
}Error Responses
404Reference type not found
Error Codes
All errors follow a consistent format with a machine-readable code and human-readable message.
Error Response Format
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error description"
}
}Error Codes Reference
| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid Authorization header |
TOKEN_EXPIRED | 401 | API token has expired |
TOKEN_REVOKED | 401 | API token has been revoked |
FORBIDDEN | 403 | Token lacks required permission |
NOT_FOUND | 404 | Requested resource does not exist |
VALIDATION_ERROR | 400 | Invalid request parameters |
RATE_LIMITED | 429 | Rate limit exceeded |
API_DISABLED | 503 | API is currently disabled by admin |
INTERNAL_ERROR | 500 | Unexpected server error |
SDK Examples
Complete examples for common use cases in different programming languages.
Fetch All Declarations with Pagination
async function fetchAllDeclarations(token) {
const declarations = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`/api/v1/declarations?page=${page}&limit=100`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();
declarations.push(...data.data);
hasMore = page < data.pagination.totalPages;
page++;
}
return declarations;
}Handle Rate Limiting
async function fetchWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After') || '60';
console.log(`Rate limited. Retrying in ${retryAfter}s...`);
await new Promise(r => setTimeout(r, parseInt(retryAfter) * 1000));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}