Getting Started

API Commons

Copy page

This page describes common patterns, headers, responses, and conventions used throughout the Partners Portal API.

Common Headers

All API requests should include the following headers:

Required Authentication Headers

Header	Type	Description	Example
x-client-id	string	Network/integrator client identifier	network_abc123
x-client-secret	string	Network/integrator secret key	secret_xyz789
correlationId	string	IC unique identifier (NIF/Tax ID)	B12345678
sessionToken	string	User session token (except auth endpoints)	eyJhbGci...

Optional Headers

Header	Type	Description	Example
Content-Type	string	Request body format (required for POST/PUT/PATCH)	application/json
Accept	string	Preferred response format	application/json

HTTP Methods

The API uses standard HTTP methods with the following semantics:

Method	Usage	Idempotent	Request Body	Response Body
GET	Retrieve resource(s)	✅ Yes	❌ No	✅ Yes
POST	Create new resource	❌ No	✅ Yes	✅ Yes
PUT	Replace entire resource	✅ Yes	✅ Yes	✅ Yes
PATCH	Partially update resource	❌ No	✅ Yes	✅ Yes
DELETE	Remove resource	✅ Yes	❌ No	⚠️ Optional

Response Format

Success Responses

All successful responses return JSON data with appropriate HTTP status codes:

200 OK - Request succeeded

Code
 
{
  "id": "123",
  "name": "Example Resource",
  "status": "active"
}

201 Created - Resource created successfully

Code
 
{
  "id": "456",
  "message": "Resource created successfully"
}

204 No Content - Request succeeded with no response body

Code
 
(Empty response body)

Error Responses

Error responses follow a consistent structure:

400 Bad Request - Invalid request data (Validation errors)

Errors follow a standard format:

• First 2 Digits represent the category of the error
• Next 2 Digits represent the specific field
• Last 2 Digits represent the specific error within that field

All errors are accompanied by a short message explaining the error and the field that caused it.

Code
 
{
    "errors": [
        {
          "errorCode": "010101",
          "errorMessage": "Missing field",
          "errorField": "InputField"
        }
    ]
}

401 Unauthorized - Authentication failed

Code
 
{
  "error": "Unauthorized",
  "message": "Invalid credentials or expired session"
}

403 Forbidden - Insufficient permissions

Code
 
{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}

404 Not Found - Resource not found

Code
 
{
  "error": "Not Found",
  "message": "The requested resource does not exist"
}

500 Internal Server Error - Server error

Code
 
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

HTTP Status Codes

Code	Meaning	Common Use Cases
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST creating a resource
204	No Content	Successful DELETE
400	Bad Request	Validation errors, malformed JSON
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate resource, business rule violation
422	Unprocessable Entity	Validation error in request data
500	Internal Server Error	Server-side error
503	Service Unavailable	Temporary server unavailability

Pagination

For endpoints returning lists, pagination is supported with query parameters:

Request:

Code
 
GET /api/simulations?page=2&pageSize=20

Response:

Code
 
{
  "data": [
    { "id": "1", "amount": 150000 },
    { "id": "2", "amount": 200000 }
  ],
  "pagination": {
    "currentPage": 2,
    "pageSize": 20,
    "totalPages": 5,
    "totalItems": 95
  }
}

Filtering and Sorting

Filtering

Use query parameters for filtering:

Code
 
GET /api/processes?status=active&type=mortgage
GET /api/simulations?minAmount=100000&maxAmount=500000

Sorting

Use the sortBy and sortOrder parameters:

Code
 
GET /api/processes?sortBy=createdDate&sortOrder=desc

Common sort fields:

• createdDate - Creation timestamp
• updatedDate - Last modification timestamp
• name - Alphabetical by name
• status - By status value

Sort orders:

• asc - Ascending
• desc - Descending

Date and Time Format

All dates and times use ISO 8601 format with UTC timezone:

Code
 
{
  "createdAt": "2026-01-16T10:30:00Z",
  "updatedAt": "2026-01-16T14:45:30.123Z"
}

When sending dates in requests, use the same format:

Code
 
{
  "birthDate": "1990-05-15T00:00:00Z"
}

ID Formats

Different resource types use different ID formats:

• Simulations: SIM-{UUID} (e.g., SIM-550e8400-e29b-41d4-a716-446655440000)
• Processes: PROC-{UUID} (e.g., PROC-123e4567-e89b-12d3-a456-426614174000)
• Partners: PART-{UUID} (e.g., PART-9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d)

Request/Response Examples

Creating a Resource (POST)

Request:

Code
 
POST /api/simulations HTTP/1.1
Host: your-api-domain.com
x-client-id: network_abc123
x-client-secret: secret_xyz789
correlationId: B12345678
sessionToken: eyJhbGci...
Content-Type: application/json

{
  "amount": 250000,
  "term": 30,
  "type": "fixed"
}

Response (201 Created):

Code
 
{
  "id": "SIM-550e8400-e29b-41d4-a716-446655440000",
  "amount": 250000,
  "term": 30,
  "type": "fixed",
  "createdAt": "2026-01-16T14:30:00Z"
}

Response (400 Bad Request - Validation Error):

Code
 
{
  "errors": [
    {
      "errorCode": "020102",
      "errorMessage": "Term must be between 1 and 40 years",
      "errorField": "term"
    }
  ]
}

Updating a Resource (PATCH)

Request:

Code
 
PATCH /api/simulations/SIM-550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: your-api-domain.com
x-client-id: network_abc123
x-client-secret: secret_xyz789
correlationId: B12345678
sessionToken: eyJhbGci...
Content-Type: application/json

{
  "amount": 275000
}

Response (200 OK):

Code
 
{
  "id": "SIM-550e8400-e29b-41d4-a716-446655440000",
  "amount": 275000,
  "term": 30,
  "type": "fixed",
  "updatedAt": "2026-01-16T14:35:00Z"
}

Response (400 Bad Request - Validation Error):

Code
 
{
  "errors": [
    {
      "errorCode": "020101",
      "errorMessage": "Amount must be greater than 0",
      "errorField": "amount"
    }
  ]
}

Retrieving a List (GET)

Request:

Code
 
GET /api/processes?status=active&page=1&pageSize=10 HTTP/1.1
Host: your-api-domain.com
x-client-id: network_abc123
x-client-secret: secret_xyz789
correlationId: B12345678
sessionToken: eyJhbGci...

Response (200 OK):

Code
 
{
  "data": [
    {
      "id": "PROC-123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "amount": 300000,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 3,
    "totalItems": 27
  }
}

CORS and Security

CORS Headers

The API supports CORS for web applications with appropriate headers:

Code
 
Access-Control-Allow-Origin: https://your-domain.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: x-client-id, x-client-secret, correlationId, sessionToken, Content-Type

Security Considerations

1. HTTPS Only - All requests must use HTTPS
2. No Credentials in URLs - Never pass sensitive data in query parameters
3. Rate Limiting - API implements rate limiting per IC and user
4. IP Whitelisting - Optional IP restriction available for networks
5. Request Signing - Critical operations may require request signatures

Rate Limiting

The API implements rate limiting to ensure fair usage:

Limits:

• 100 requests per minute per IC
• 1000 requests per hour per IC

Rate Limit Headers:

Code
 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705410600

When rate limit is exceeded:

Response (429 Too Many Requests):

Code
 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "retryAfter": 45
}

Validation

Request Validation

All request data is validated before processing, with possible validation errors returned in the response:

Response (422 Unprocessable Entity - Validation Error):

Code
 
{
  "error": "Validation Error",
  "message": "Invalid request data",
  "validationErrors": [
    {
      "field": "amount",
      "message": "Amount must be greater than 0"
    },
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Common Validation Rules

• Email: Valid email format required
• Phone: International format (E.164) preferred
• Amounts: Positive numbers, max 2 decimal places
• Dates: ISO 8601 format
• IDs: Valid UUID or prefixed format

Versioning

The API version is included in the base path:

Code
 
https://your-api-domain.com/api/v1/...

Breaking changes will result in a new version (v2, v3, etc.)

Best Practices

1. Always Include All Authentication Headers - Network, IC, and session credentials
2. Handle Errors Gracefully - Check status codes and parse error responses
3. Implement Retry Logic - Use exponential backoff for transient errors
4. Cache Reference Data - Taxonomies change infrequently
5. Use Pagination - Don't request all data at once for large datasets
6. Monitor Rate Limits - Track rate limit headers to avoid throttling
7. Validate Before Sending - Client-side validation reduces errors
8. Log correlationId - Use for tracking requests across systems

Next Steps

• Authentication - Detailed authentication guide
• API Reference - Complete endpoint documentation
• Introduction - API overview and getting started