​
API Conventions

Prove Platform APIs follow consistent API conventions. The API responses follow these conventions:

  • Optional fields that have no values aren’t returned.

  • JSON maps that have no values aren’t returned.

  • JSON arrays that have no values aren’t returned.

​
HTTP Status Codes

The following table has a list of the HTTP status codes returned by the Prove services:

CodeDefinitionDescription
200OKRequest completed successfully.
400Bad RequestThere was a problem with the submitted request.
401UnauthorizedThe request lacks valid authentication credentials for the target resource.
403ForbiddenThe client does not have permission to access the target resource.
404Not FoundThe server did not find anything matching the Request-URI.
500Internal Server ErrorThe server encountered an unexpected condition preventing it from fulfilling the request. Retry the request, and if the problem persists, contact Prove support.

​
API Error Codes

When a Prove API encounters a request error, the JSON response object includes a code field and a message field to give further context.

The table has a list of the API error codes:

Error CodeDescriptionResolution Path
8000Internal ErrorThe server encountered an unexpected condition preventing it from fulfilling the request. Retry the request, and if the problem persists, contact Prove support.
8001Malformed RequestEnsure the request is valid JSON, is under 4 KB in size, and correct any invalid parameters. Invalid parameters are specified with the reason in the message field.
8002Unauthorized RequestThe request lacks valid authentication credentials for the target resource - ensure the correct credentials were used.
8003Step Called Out of OrderThe request called an endpoint out of order. Check the next field for the proper endpoint to call.
8007Sandbox User Not FoundEnsure in Sandbox environment, only test user information is used as input for requests unless otherwise specified in the test cases.
8008Invalid Correlation IDEnsure the correct Correlation ID is used as input for all endpoints other than Start. The Correlation ID is unique per user/session and cannot be used across transactions.
8009Sandbox Test User Access DeniedIn the sandbox environment, the test user cannot be accessed with your current product credentials. Ensure you’re using Pre-Fill test users with Pre-Fill credentials and Identity test users with Identity credentials.
8010Unauthorized for CountryThis can mean one of two things:
  • The customer is not authorized to verify numbers for the requested country. In this case, please contact your Prove representative.
  • An EU number is being passed to our US endpoint, or vice versa. In this case, please use the correct endpoint for the given phone number.

​
Example Success and Error Responses

EndpointHTTP CodeResponse Body
Any400{"code":8001,"message":"field 'correlationId' length cannot be greater than 36 characters"}
Any400{"code":8007,"message":"no test user found matching the phone number"}
Any401{"code":8002,"message":"not authorized"}
Any403{"code":8003,"message":"step not allowed"}
Any403{"code":8008,"message":"correlationId is expired or invalid"}
Any500{"code":8000,"message":"error at prove, try again later"}
Start200{"correlationId":"0a53cbf8-4053-4d6a-9ef4-ebebc8f26811","authToken":"eyJ...","next":\{"v3-validate":"/v3/validate"}}
Start400{"code":8001,"message":"field 'flowType' is missing"}
Start400{"code":8001,"message":"field 'flowType' must be one of these values: desktop mobile"}
Start400{"code":8001,"message":"field 'ssn' length cannot be greater than 9 characters"}
Start400{"code":8001,"message":"field 'ssn' must be numeric"}
Start400{"code":8001,"message":"field 'dob' must be in date format: YYYY-MM-DD, YYYY-MM, or MM-DD"}
Validate200{"success":true,"challengeMissing":false,"phoneNumber":"2001001686","next":\{"v3-challenge":"/v3/challenge"}}
Validate200{"success":true,"challengeMissing":false,"phoneNumber":"2001001686","next":\{"v3-complete":"/v3/complete"}}
Validate200{"success":false,"challengeMissing":false,"next":\{"done":"done"}}
Validate200{"success":true,"challengeMissing":true,"phoneNumber":"2001001686","next":\{"v3-challenge":"/v3/challenge"}}
Challenge200{"success":true,"individual":\{USER INFO...},"next":\{"v3-complete":"/v3/complete"}}
Challenge200{"success":false,"next":\{"v3-complete":"/v3/complete"}}
Challenge400{"code":8001,"message":"field 'ssn' length cannot be greater than 9 characters"}
Challenge400{"code":8001,"message":"field 'ssn' must be numeric"}
Challenge400{"code":8001,"message":"field 'dob' must be in date format: YYYY-MM-DD, YYYY-MM, or MM-DD"}
Complete200{"success":true,"next":\{"done":"done"}}
Complete200{"success":false,"next":\{"done":"done"}}
Complete400{"code":8001,"message":"field 'ssn' length cannot be greater than 9 characters"}
Complete400{"code":8001,"message":"field 'dob' must be in date format: YYYY-MM-DD, YYYY-MM, or MM-DD"}

​
Retry Behavior After Errors

When a status code other than 200 returns, you can fix and retry the request. If you retry a request that resulted in 200, you receive an HTTP 403 code with either:

  • step called out of order
  • correlation ID is expired or invalid Prove prevents retries to ensure proper behavior and mitigate issues with replay attacks.