Submit Signup API Request and Response Schema Guide

API Response Codes and Structures

Our API uses standard HTTP status codes and JSON response bodies. This guide explains the success and error responses you may encounter.

📌 Clarification on HTTP Status Codes vs Response Body

For all errors such as 503 Service Unavailable, the HTTP status code is returned in the HTTP response line/headers, not inside the JSON body. This is standard REST API behavior.

The JSON body contains the message (and, when applicable, a detail[] array). The actual code (e.g., 503, 400, 500) is conveyed in the HTTP response line/headers.

Example: 503 Service Unavailable

Request

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "John",
        "last_name": "Doe",
        "dob": "1990-12-01",
        "email": "john.doe@email.com"
      }'

Response

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 7b1c5c6e-1a2b-4dc9-9ac2-2a31b1aa2e10

{
  "message": "Required third-party service is temporarily unavailable"
}

Note: You will not see statusCode in the JSON body; the status is already provided by HTTP/1.1 503 Service Unavailable above.

✅ 200 OK — Successful Responses

The API returns different success responses based on the decision outcome. All success responses share a common structure with variations in the data object.

Common Success Response Structure

Field Type Required Description Example
data Object Yes Container for all response data —
data.status String Yes Transaction status code "1"
data.formKey String Yes Unique form identifier "v98765432109876"
data.url String Yes JWT URL parameter "?instntjwt=..."
data.success Boolean Yes Operation success flag true
data.instntjwt String Yes JWT token "eyJhbGciOiJSUzI1NiIs..."
data.decision String Yes Business decision "ACCEPT", "REVIEW", "REJECT"
data.is_insured Boolean Conditional Insurance status (ACCEPT decisions only) true/false

1) REVIEW Decision

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 2d9d1a32-1c7e-4cb2-8dbf-0e8a1b1fbe21

{
  "data": {
    "status": "1",
    "formKey": "v98765432109876",
    "url": "?instntjwt=eyJhbGciOiJSUzI1NiIsInR...",
    "success": true,
    "instntjwt": "eyJhbGciOiJSUzI1NiIsInR...",
    "decision": "REVIEW"
  }
}

2) ACCEPT Decision

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 5a318b6a-9d7c-4f09-83a3-3f8c1f0a45d0

{
  "data": {
    "status": "1",
    "formKey": "v98765432109876",
    "url": "?instntjwt=eyJhbGciOiJSUzI1NiIsInR...",
    "success": true,
    "instntjwt": "eyJhbGciOiJSUzI1NiIsInR...",
    "decision": "ACCEPT",
    "is_insured": true
  }
}

3) REJECT Decision

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: a4a6f2e8-3f3a-4a1a-9d6f-b9e0e2bcd0f1

{
  "data": {
    "status": "1",
    "formKey": "v98765432109876",
    "url": "?instntjwt=eyJhbGciOiJSUzI1NiIsInR...",
    "success": true,
    "instntjwt": "eyJhbGciOiJSUzI1NiIsInR...",
    "decision": "REJECT"
  }
}

❌ Error Responses

400 Bad Request — Client Errors

These occur when a request is invalid. All 400 errors include a message field and, when applicable, a detail[] array describing the field-level error.

1. Resubmission Interval Limit Exceeded

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 9ef2a9d0-6f0f-4d2e-9e2d-8b5bfac7d222

{
  "message": "Transaction resubmission interval limit exceeded",
  "detail": [
    {
      "field": "resubmission_interval",
      "issue": "Exceeded interval limit of 60 minutes"
    }
  ]
}

2. Resubmission Limit Exceeded

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 3b6d4c52-7b07-4a3a-a8a8-7dc9e2a1a0b9

{
  "message": "Transaction resubmission limit exceeded",
  "detail": [
    {
      "field": "resubmission_count",
      "issue": "Exceeded resubmission limit of 1"
    }
  ]
}

3. Field Validation Errors

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "x-12-04",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 0c8e7a19-7c71-4f8d-9aa1-2d19e1244d33

{
  "message": "Date x-12-04 is invalid. Exception: time data 'x-12-04' does not match format '%Y-%m-%d'",
  "detail": [
    {
      "field": "dob",
      "issue": "Invalid",
      "form_key": "v98765432109876"
    }
  ]
}

4. Utility Function Errors

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: e27b20bf-4b93-4a84-bb16-2a9a1a7d9f52

{
  "message": "Something went wrong in utility function"
}

503 Service Unavailable

Occurs when a required third-party service is temporarily unavailable.

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: 6e2f2a2d-1f45-4e9f-a2f1-0a5f4b3c2d11

{
  "message": "Required third-party service is temporarily unavailable"
}

Triage Note: This is typically a transient error. It is recommended that you configure your scripting to retry (with exponential backoff and a max cap) if you encounter this status in our headers.

500 Internal Server Error — Uncaught Errors

Represents uncaught system failures.

Request 

curl -X POST "https://api.company.com/v1/signup/submit" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "first_name": "Jane",
        "last_name": "Smith",
        "dob": "1991-05-20",
        "email": "jane.smith@email.com"
      }'

Response 

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
Cache-Control: no-store
Date: Tue, 01 Oct 2025 10:20:00 GMT
X-Request-Id: d1df3f1b-9c4d-4f80-9b31-2c7a8f91d0aa

{
  "error": "Internal Server Error",
  "message": "Unknown failure occurred"
}

🌐 Standard HTTP Status Codes

Status Code Description Use Case
404 Not Found Resource not found
405 Method Not Allowed HTTP method not supported
408 Request Timeout Request processing timeout

📋 Response Summary Table

Scenario HTTP Status Content-Type Key Fields Decision Types
Success 200 application/json data, decision, is_insured ACCEPT, REVIEW, REJECT
Resubmission Errors 400 application/json message, detail[] —
Field Validation 400 application/json message, detail[] —
Utility Errors 400 application/json message —
Service Unavailable 503 application/json message —
Internal Errors 500 application/json error, message —
Standard Errors 404, 405, 408 — — —

🔐 Notes

  • All responses use the application/json content type.
  • 400 errors provide detailed field-level validation information.
  • 503 errors indicate temporary unavailability of required services; implement retries with backoff.
  • Security: JWT tokens in production are actual encoded tokens; examples show masked values.