mobo_img.jpg
mobo_img.jpg
mobo_img.jpg

Identification API


SCROLL DOWN

Identification API


Introduction

The Identification API is a REST-based interface to our identity verification services. Before making API calls, you will need to contact our Developer Relations group to receive credentials and get your server IP addresses white-listed.

schema

Here we discuss the general format for endpoints, status codes, and content.

URL

The URL schema for the API is:

https://{domain}/identification/api/{version}/{resource}

The meaning of each token is:

Token Description
{domain} You will receive the domain name at the time you receive your credentials.
{version} The version you want to communicate with (ex. v1 or v2).
{resource} The resource you want to perform operations on.

Example
The endpoint https://qaservices.goldstartrust.com/identification/api/v1/ops/ping will return the current date & time from the server.

HTTP Headers

Header Description
X-ApiKey You will receive your api key from Goldstar Trust. All api calls will require this header.

json

All data is sent and received as JSON.

operations

Because the Identification API is REST-based, we use HTTP verbs for all operations.

Status Codes

Response will have one of the following status codes. 

Verb Description
GET Select one or more resources and respond with results in the body.
POST Create or invoke behavior on a resource and respond with results in the body.
PUT Update an existing resource and respond with results in the body.
DELETE Delete an existing resource and respond with nothing in the body.
CodeDescription
200 Success - requested resource is in the response
201 Success - the newly created resource is in the response
204 Success - but no content to return
400 Bad - could not be understood bythe server
401 Unauthorized - requested resource requires authentication.
404 Not Found - requested resource requires authentication.
422 Unprocessable Entity - requested resource requires authentication
500 Internal Server Error - generic error occurred on the server


Security

All API calls will require the HTTP header X-ApiKey listed above

Tools

We like using Postman when working with the API.

Change log

TDB

mobo_img.jpg

Identification API Reference


Identification API Reference


Reference

Operations

Use this resource endpoint to perform validations

Ping

This operation returns the current date & time as a string based on the server time zone. 

POST /ops/ping

Response

Status: 200 OK
Content-Length: 35

"2015-03-20T13:50:10.0370495-05:00"

Verify Identity

This operation accepts the given payload and attempts to verify the identity with out service provider. If the call "Fails," you may be presented with four verify questions to give the user a chance to "Pass" CIP.

POST /ops/verify-identity

Payload

The following parameters are required and must be included in the payload. 

Name Type Description
firstname string First name of the identity to verify
lastname string Last name of the identity to verify
address string Street address of the identity to verify
city string City of the identity to verify.
state string State of the identity to verify.
zip string Zip of the identity to verify.
taxpayerID string Social security number of the identity to verify.
birthMonth number Birthday month of the identity to verify.
birthDay number Birthday day of the identity to verify.
birthYear number Birthday year of the identity to verify.

Example of Successful Request/Response for verify-identity – Please note the “Id” returned in the Response. This Id will need to be sent with Account payload when calling the CrowdPay “Create Account” api.

Example of Hard failed Request/Response for verify-identity – Bad SSN

Example of Soft Fail Request/Response for verify-identity – You will get a list of 4 verify questions for a second chance to pass CIP. Verify-answers api call is used to attempt to answer questions.

Actual JSON response from failed verify-identity api call with verify questions returned in the response.

{
    "Id": "1199927326",
    "Key": "id.failure",
    "Message": "FAIL",
    "Qualifiers": [{
        "Key": "resultcode.yob.does.not.match",
        "Message": "YOB Does Not Match"
    }],
    "Questions": [{
        "Prompt": "What type of residence is 222333 PEACHTREE PLACE?",
        "Type": "residence.type",
        "Choices": [{
            "Text": "Single Family Residence"
        }, {
            "Text": "Townhome"
        }, {
            "Text": "Apartment"
        }, {
            "Text": "None of the above"
        }, {
            "Text": "Skip Question"
        }]
    }, {
        "Prompt": "Which person is not a relative or someone that you know?",
        "Type": "person.not.known",
        "Choices": [{
            "Text": "DENYSE SMITH"
        }, {
            "Text": "ANTHONY BROWN"
        }, {
            "Text": "DAVID BROWN"
        }, {
            "Text": "None of the above"
        }, {
            "Text": "Skip Question"
        }]
    }, {
        "Prompt": "In which city is ANY STREET?",
        "Type": "city.of.residence",
        "Choices": [{
            "Text": "PAULDING"
        }, {
            "Text": "THORNTON"
        }, {
            "Text": "ATLANTA"
        }, {
            "Text": "None of the above"
        }, {
            "Text": "Skip Question"
        }]
    }, {
        "Prompt": "Between 1979 and 1980, in which State did you live?",
        "Type": "prior.residence.state.multiyear",
        "Choices": [{
            "Text": "WASHINGTON"
        }, {
            "Text": "KENTUCKY"
        }, {
            "Text": "NEW YORK"
        }, {
            "Text": "None of the above"
        }, {
            "Text": "Skip Question"
        }]
    }]
}

Verify Answers

This operation accepts the given payload and attempts to verify the identity with our service provider by providing responses to the verify questions from a failed attempt on the verify-identity api call.

POST /ops/verify-answers

Payload

The following parameters are required and must be included in the payload.

Name Type Description
id number The id returned by the failed verify-identity api call. Needed to respond to verify questions from failed verify-identity api call.
answers collection Collection of responses to verify questions
answers.type string Type of response
answers.text string Text chosen from verify questions.
{
    "id": "1196338064",
    "answers": [{
        "type": "time.at.current.address",
        "text": "Over 5 years",
    }, {
        "type": "purchased.property.from",
        "text": "JOE ANDERSON",
    }, {
        "type": "prior.residence.state.multiyear",
        "text": "NEW YORK",
    }, {
        "type": "city.of.residence",
        "text": "ATLANTA",
    }]
}