About the API

The Customer Portal integration API is a powerful RESTful API that enables you to create, update, and manage business services through our platform. Designed to be dynamic, flexible, and developer-friendly, our API seamlessly integrates with your applications to streamline business formation and compliance processes.

After successfully placing orders through the Trademark Engine API, you can provide your users with a seamless post-order experience through our Customer Portal integration. This portal enables your customers to:

• Monitor order progress in real-time
• Complete required questionnaires
• Access and manage business documents
• Purchase additional services
• Handle compliance requirements
• Respond to any order rejections or requests for information

API Specification

The Customer Portal integration API is fully compliant with the OpenAPI Specification, making it easy to integrate with your applications. You can find the OpenAPI Specification in the following links:

• View and try API Specification
• Download API Specification

📝 Note: The API Specification is a work in progress and is subject to change.

Authentication

The Customer Portal integration API uses OAuth 2.0 authentication for secure access to endpoints. To authenticate with the API, you must:

1. Initial Authentication: Use your username and password credentials to obtain an access token
2. Token Usage: Include the access token in the Authorization header for all API requests
3. Token Expiration: Access tokens have a limited lifespan and will expire after a set period
4. Token Refresh: Use the refresh token to obtain a new access token without re-entering credentials

The authentication flow ensures secure access while providing a seamless experience for your applications.

OAuth 2.0 Authentication

Our platform utilizes the OAuth 2.0 protocol for secure server-to-server authentication, enabling vendors and white-label clients to access protected resources without direct user involvement. OAuth 2.0 is an industry-standard authorization framework that ensures secure and scalable interactions between systems.

Upon onboarding, clients are issued the following credentials:

• client_id: A unique identifier for your application.
• client_secret: A confidential key used to authenticate your application.

These credentials are required to obtain an access token, which must be included in the Authorization header of all secured API requests.

Example Credentials

For testing on the QA server, use the following credentials:

• client_id: xyz
• client_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Obtaining an Access Token

To interact with our APIs, you must first obtain an access token by making a POST request to the token generation endpoint. The access token is a JSON Web Token (JWT) that authenticates your API requests.

Endpoint

POST /api/vendor/generate-token

Request Headers

Header	Value
Content-Type	application/json
Accept	application/json

Request Body

The request body must be a JSON object containing your client_id and client_secret.

{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
}

Example cURL Request

curl --request POST \
 --url https://api.trademarkengine.com/api/vendor/generate-token \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --data '{
"client_id": "xyz",
"client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

Response

Upon successful authentication, the server responds with a JSON object containing the access token and related metadata.

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "xxxxxxxxxxxxxxx..."
}

Response Fields

Field	Description
token_type	The type of token issued (always Bearer).
expires_in	The token’s validity period in seconds (e.g., 31,536,000 seconds = 1 year).
access_token	The JWT token to be used in the Authorization header for API requests.

Action: Store the access_token securely and use it in subsequent API requests.

Making Authenticated API Requests

Once you have the access token, you can use it to make authenticated requests to our APIs. The access token must be included in the Authorization header as a Bearer token.

Example Endpoint

GET /api/vendor/user/{userId}/get-orders

Request Headers

Header	Value
Authorization	Bearer YOUR_ACCESS_TOKEN
Accept	application/json

Example cURL Request

curl --request GET \
 --url https://api.trademarkengine.com/api/vendor/user/123/get-orders \
 --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLC...' \
 --header 'Accept: application/json'

Response

The API returns a JSON response with the requested data.

{
    "success": true,
    "message": "",
    "data": [
        {
            "mark": "Mark Name",
            "created_at": "2020-09-03T17:51:58.000000Z",
            "updated_at": "2025-03-12T17:48:36.000000Z"
        }
    ]
}

Response Fields

Field	Description
success	Boolean indicating whether the request was successful.
message	Optional message providing additional context (e.g., errors).
data	Array of objects containing the requested resource data.

Error Handling

To ensure robust integration, handle the following HTTP status codes appropriately:

Status Code	Description	Action
200 OK	Request successful.	Process the response data.
401 Unauthorized	Invalid or expired access token.	Regenerate the access token using the /api/vendor/generate-token endpoint.
400 Bad Request	Invalid request parameters or payload.	Verify the request body and parameters.
403 Forbidden	Insufficient permissions.	Contact support to verify your customer permissions.
500 Internal Server Error	Server-side issue.	Retry the request after a delay or contact support if persistent.

Example Error Response (401 Unauthorized)

{
    "success": false,
    "message": "Invalid or expired token"
}

Best Practices

To ensure secure and efficient API integration, adhere to the following best practices:

1. Secure Credential Storage:

• Store client_id and client_secret in a secure environment (e.g., environment variables or a secrets management system).
• Never expose credentials in client-side code, public repositories, or unencrypted storage.

2. Token Management:

• Access tokens are valid for 1 year (31,536,000 seconds). Monitor the expires_in value and regenerate tokens proactively before expiration.
• Cache the access token securely to minimize token generation requests, but ensure it is refreshed when a 401 Unauthorized response is received.

3. Error Handling:

• Implement robust error handling to manage 401, 400, 403, and 500 status codes gracefully.
• Log errors with sufficient context (e.g., request details, response status, and message) for debugging.

4. HTTPS Only:

• Always use HTTPS for API requests to ensure data security and integrity.

5. Testing in QA Environment:

• Use the provided QA credentials and environment for testing before deploying to production.
• Validate all API workflows in the QA environment to avoid production issues.

Security

• API endpoints are secured using Bearer tokens.
• Access Keys must be requested to Customer Portal integration Team and are subject to approval.
• Access Keys can be revoked at any time if compromised.
• Access Keys must be kept secret and only used on server-side applications.
• Implementation and usage of keys must follow security best practices.

API Key Management Best Practices

• Securely store your API keys using environment variables or secure configuration.
• Never commit API keys to version control.
• Implement key rotation procedures for production environments. We may revoke keys periodically with a 30 day previous notice, so make sure you can replace keys easily.