NAV
bash

Introduction

On this side of the page, you’ll see some helpful examples of how to communicate with our APIs. Try them out!

Sandbox API Endpoint: https://sandbox.alloy.co

Welcome to Alloy! We’re making identity verification APIs that make KYC/AML effective and simple, and on this page we show you how to use them. Some of the things you can do with this API include:

Our API rules are as follows:

  1. All APIs are based on REST
  2. APIs return JSON by default
  3. You must use HTTPS, we’re not sending you any data over insecure channels

Using the Dashboard

If you’re just integrating the API and your company already has credentials, feel free to skip this. If you want to learn how the API is configured, watch this short video to get acquainted with our dashboard.

Authentication

Basic HTTP authentication and OAuth 2.0 are both supported depending on the security requirements and technical limitations of the organization. Each of your applications is issued a application_token and application_secret (viewable in your dashboard) that are used in either method.

Basic HTTP Authentication

To authorize per-request with HTTP basic auth, use this code:

curl -X POST https://sandbox.alloy.co/v1/evaluations \
     -H "Content-Type: application/json" \
     -u application_token:application_secret \
     -d $'{
       "name_first": "John",
       ...
     }'

If choosing to use HTTP basic auth, credentials must be passed for each request with the username being the application_token and the password as the application_secret. To implement HTTP basic auth yourself, the steps are as follows:

  1. Concatenate the application token and application secret together, separated by a colon
  2. Base64 encode the resulting string
  3. Pass the result in the authorization header, prefixed with the word “Basic” like Basic base64_encode(application_token:application_secret)

OAuth 2.0

To authorize once with OAuth 2.0, use this code:

curl -X POST https://sandbox.alloy.co/v1/oauth/bearer \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic ZHBERDZ6NG9sT1NJN040Zk1Dc0FsS2pGYTdyZUJZaHU6b0ptM25pUVgxUGR5NHo2NzVrZWZFSUtCZ0ZuOXRRNDU=" \
  -d '{
    "grant_type": "client_credentials"
  }'

If choosing to use OAuth, the application credentials must first be passed to a route in order to receive a bearer token. Each bearer token is valid for one hour. Alloy uses standard OAuth 2.0, so it is generally plug-and-play with most auth plugins or API clients. All you need to know is:

If you want to roll your own, just pass the application token and application secret via basic auth (as explained above) to POST /oauth/bearer with a grant type of “client_credentials”.

Alloy expects for the bearer token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <bearer_token>

Versioning

Check out our changelog pages for a full version history, feature list for each release, and upcoming releases you can look forward to. We’re always backwards compatible on patches and minor changes, so there’s no need to worry!

We use semantic versioning so you can know how a new version will affect your application even before you see what it is. The simple breakdown is <major version>.<minor version>.<patch version> where:

We version our API releases in the URL. By default, if you pass nothing, the request will be sent to the latest API version. If you want to pin an API version in your application, simply pass the version between the base URL and the resource like this: https://sandbox.alloy.co/v1/evaluations.

Currently, the only supported version is v1.

Customer Onboarding

Get Parameters Needed for Evaluation

curl -X GET https://sandbox.alloy.co/v1/parameters \
    -u application_token:application_secret

The response will be a list of parameters that are either required, optional, or required in certain “or” groups

{
  "required": [
    {
      "key": "email_address",
      "type": "string",
      "description": "Primary email address",
      "regex": ""
    },
    {
      "key": "name_first",
      "type": "string",
      "description": "First name",
      "regex": "^[^d]*$"
    },
    {
      "key": "name_last",
      "type": "string",
      "description": "Last name",
      "regex": "^[^d]*$"
    },
    {
      "key": "address_country_code",
      "type": "string",
      "description": "Two character ISO 3166-1 alpha-2 country code",
      "regex": ""
    }
  ],
  "optional": [
    {
      "key": "address_line_2",
      "type": "string",
      "description": "Address field 2",
      "regex": ""
    },
    {
      "key": "phone_number",
      "type": "string",
      "description": "Primary phone number",
      "regex": ""
    }
  ],
  "or": [
    {
      "required": [
        {
          "key": "document_license",
          "type": "string",
          "description": "US issued drivers license number",
          "regex": ""
        },
        {
          "key": "document_license_state",
          "type": "string",
          "description": "US state",
          "regex": ""
        }
      ]
    },
    {
      "required": [
        {
          "key": "document_ssn",
          "type": "string",
          "description": "US social security number"
        }
      ]
    }
  ]
}

Our API is very dynamic, and thus the input parameters vary greatly depending on which services are run and how the application is configured. Hitting the GET /parameters endpoint will show exactly what your initial request to the Alloy API should look like. All attributes will either be “required”, “optional”, or required in certain cases. For instance, in the case to the right, you either have to pass document_ssn OR document_license and document_license_state.

HTTP Request

GET https://sandbox.alloy.co/v1/parameters

Onboard a Person

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Content-Type: application/json" \
  -u application_token:application_secret \
  -d $'{
    "phone_number": "18042562188",
    "name_first": "John",
    "name_last": "Doe",
    "email_address": "john.doe@example.com",
    "birth_date": "1985-01-23",
    "address_line_1": "1717 E Test St",
    "address_city": "Richmond",
    "address_state": "VA",
    "document_ssn": "123456789",
    "address_postal_code": "23220",
    "address_country_code": "US",
    "social_twitter": "dog_rates"
  }'

If successful, the above command returns JSON structured like this:

{
  "status_code": 201,
  "error": null,
  "timestamp": 1497309594913,
  "evaluation_token": "S-BNTwVDLrlRvHbKVhRa8X",
  "entity_token": "P-2WU9staJ5pVCQ6xgn3KV",
  "application_token": "token",
  "application_version_id": 14,
  "summary": {
    "result": "success",
    "score": 0.99,
    "tags": ["Address Match", "Phone Match"],
    "outcome": "Approved",
    "services": {
      "Emailage": "executed",
      "Socure": "executed",
      "White Pages Pro": "executed"
    }
  },
  "supplied": {
    "phone_number": "18042562188",
    "name_first": "John",
    "name_last": "Doe",
    "email_address": "john.doe@example.com",
    "birth_date": "1985-01-23",
    "address_line_1": "1717 E Test St",
    "address_city": "Richmond",
    "address_state": "VA",
    "document_ssn": "123456789",
    "address_postal_code": "23220",
    "address_country_code": "US",
    "social_twitter": "dog_rates"
  },
  "formatted": {
    "phone_number": "+18042562188",
    "name_first": "John",
    "name_last": "Doe",
    "email_address": "john.doe@example.com",
    "birth_date": "1985-01-23",
    "address_line_1": "1717 E Test St",
    "address_city": "Richmond",
    "address_state": "VA",
    "document_ssn": "123456789",
    "address_postal_code": "23220",
    "address_country_code": "US",
    "social_twitter": "dog_rates"
  },
  "matching": {
    "name": {
      "score": 0.99,
      "matched": ["Emailage", "Socure"],
      "unmatched": []
    },
    "phone": {
      "score": 1,
      "matched": ["White Pages Pro", "Socure"],
      "unmatched": []
    },
    "address": {
      "score": 1,
      "matched": ["White Pages Pro", "Socure"],
      "unmatched": []
    },
    "email": {
      "score": 0.99,
      "matched": ["White Pages Pro", "Socure"],
      "unmatched": []
    },
    "ssn": {
      "score": 0.99,
      "matched": ["Socure"],
      "unmatched": []
    },
    "dob": {
      "score": 0.99,
      "matched": ["Socure"],
      "unmatched": []
    }
  },
  "diligence": {
    "watchlists": {
      "lists": ["BES", "CFTC", "DTC", "EUDT", "FBI", "FCEN", "FAR", "IMW", "OFAC", "OCC", "OSFI",
        "PEP", "SDT", "UNNT", "BIS", "WBIF", "Socure Watchlists Tier 1"
      ],
      "matches": []
    },
    "fraud": {
      "score": 0.02,
      "flags": []
    },
    "financial": null,
    "identity_questions": null
  },
  "related_data": {
    "social": [{
      "type": "Twitter",
      "url": "https://twitter.com/blankslateio",
      "id": "blankslateio"
    }, {
      "type": "Klout",
      "url": "http://klout.com/blankslateio",
      "id": "blankslateio"
    }, {
      "type": "Twitter",
      "url": "https://twitter.com/dog_rates",
      "id": "dog_rates"
    }]
  },
  "raw_responses": {
    "Emailage": [ ... ],
    "White Pages Pro": [ ... ],
    "Socure": [ ... ]
  },
  "formatted_responses": {
    "Emailage": { ... },
    "White Pages Pro": { ... },
    "Socure": { ... }
  },
  "audit_archive": null
}

If more information is needed, the response is going to look something like this:

{
  "evaluation_token": "S-eJ38yUNDqcMxKwwdxbya",
  "error": null,
  "timestamp": 1475258667031,
  "entity_token": "P-Hp6QxEGwNg6sgYNuXdqF",
  "application_token": "token",
  "application_version_id": 11,
  "required": [
    {
      "key": "answers",
      "type": "object",
      "description": "Object containing answers to out of wallet question prompts.",
      "template": {
        "answers": [
          {
            "question_id": 1,
            "answer_id": 0
          },
          {
            "question_id": 2,
            "answer_id": 0
          },
          {
            "question_id": 3,
            "answer_id": 0
          },
          {
            "question_id": 4,
            "answer_id": 0
          },
          {
            "question_id": 5,
            "answer_id": 0
          }
        ]
      }
    }
  ],
  "optional": [],
  "prompts": {
    "answers": {
      "questions": [
        {
          "id": 1,
          "question": "What state was your SSN issued in?",
          "answers": [
            {
              "id": 1,
              "answer": "Arkansas"
            },
            {
              "id": 2,
              "answer": "Alabama"
            },
            {
              "id": 3,
              "answer": "West Virginia"
            },
            {
              "id": 4,
              "answer": "Virginia"
            },
            {
              "id": 5,
              "answer": "None Of The Above"
            }
          ]
        },
        <...>
      ]
    }
  }
}

This endpoint is for creating a user and running all KYC checks that you have selected for your onboarding flow. If we are able to resolve the person and there is no need for further information, the response will return all the attributes we were able to match and deduce from the services that were run. If more information is needed, the response will indicate what is needed and what the format for that information should be.

HTTP Request

POST https://sandbox.alloy.co/v1/evaluations

Query Parameters

Parameter Example
name_first* John
name_last* Doe
phone_number 18042562188
email_address john.doe@example.com
address_line_1 41 Elizabeth Street
address_line_2 STE 500
address_city New York
address_state NY
address_postal_code 10013
address_country_code US
birth_date 1985-06-13
document_ssn 123456789

* required fields (depends on your application and what data sources are used!)

Response Explanation

Key Description
status_code HTTP status code indicating the state of the request
error Any error codes that have arisen from the request
timestamp Time of request
evaluation_token ID of the evaluation, must be passed back to PATCH /evaluations if necessary
entity_token ID of the entity you are investigating. This can be used to trace an entity across multiple requests
application_token Token of the application that was run
application_version_id Version of the application that was run
summary Overall summary object
summary.result Status of the request (success, partial, fail)
summary.tags Tags that were added to the request during processing (e.g. “Address Matched” or “Credit Pass”)
summary.outcome Top-level onboarding decision. This can be configured in the “Set Outcome” tab within the application flow
summary.score Normalized score across multiple identity and risk dimensions for this request
summary.services Array of services that were run during this request
supplied Object showing each supplied attribute from the request body
formatted Formatted values for all supplied attributes (using USPS data, ISO formatting, etc. based on data type)
matching Object showing which data attribute inputs matched the results of services
matching.[attr].score Overall match score of this attribute across all services (between 0 and 1)
supplied.[attr].matched Services that matched the supplied data
supplied.[attr].unmatched Services that did not match the supplied data
diligence Object containing derived insights such as AML or fraud risk data
diligence.watchlists AML critical flags or warnings (such as OFAC or PEP)
diligence.fraud Any fraud-related critical flags or warnings
diligence.financial Data from credit or banking sources
diligence.identity_questions Information and scores from knowledge based authentication questions
related_data Extra data that may be useful but is not guaranteed to return
raw_responses Raw responses from each of the services that were run
formatted_responses Alloy-formatted responses from each of the services that were run. We try to structure these in a consistent way so it is easier to set rules on them than the raw service responses.
audit_archive A link to the full audit archive for this request. Access to audits is only available with extended due diligence integrations.

Additional Data and Question Responses

curl -X PATCH https://sandbox.alloy.co/v1/evaluations/S-uNBOm9GLnnzIjYwlw12K \
    -u application_token:application_secret \
    -H "Content-Type: application/json" \
    -d $'{"answers":[
        {"question_id": 1, "answer_id": 1},
        {"question_id": 2, "answer_id": 5},
        {"question_id": 3, "answer_id": 2},
        {"question_id": 4, "answer_id": 1},
        {"question_id": 5, "answer_id": 5}
      ],
      "name_first": "John",
      "name_last": "Doe"
    }'

This endpoint should be called to provide additional info to an onboarding evaluation. This may be due to a lack of required information, invalid input in previous steps, or additional knowledge based authentication questions. The response from POST /evaluations will indicate which parameters need to be passed and the datatype/ format they should be passed in. The last URL attribute is the evaluation token from the initial request, indicating which evaluation this data is to be added to. If nothing further is needed, the response will be the same as that to POST /evaluations, returning all the same fields and in the same format. If more information is still needed, it is possible that PATCH /evaluations will need to be called again.

HTTP Request

PATCH https://sandbox.alloy.co/v1/evaluations/<evaluation_token>

Entities

curl -X GET https://sandbox.alloy.co/v1/entities/<entity_token> \
  -H "Content-Type: application/json" \
  -u application_token:application_secret

If successful, the above command returns JSON structured like this:

{
  "name": "John Doe",
  "type": "person",
  "entity_token": "P-1OFFS4vGzxIEqe0WZd2m",
  "archived": false,
  "created": 1496760103793,
  "evaluations": [
    {
      "evaluation_token": "S-08dl6ZdQULhEEAcxPgLh",
      "timestamp": 1497387918670,
      "status": "waiting",
      "application_name": "Customer Onboarding",
      "outcome": null
    },
    {
      "evaluation_token": "S-f2QKj3v36bJCQJDvtAos",
      "timestamp": 1497387980920,
      "status": "complete",
      "application_name": "Customer Onboarding",
      "outcome": "manual review"
    },
    {
      "evaluation_token": "S-RE4zmiVAVaN78Ap6uhbm",
      "timestamp": 1497391523620,
      "status": "complete",
      "application_name": "Customer Onboarding",
      "outcome": "approved"
    }
  ],
  "documents": [
    {
      "document_token": "D-XOxaoWMP9PDLCPLrC7da",
      "timestamp": 1496849815081,
      "type": "license",
      "name": "John Doe Drivers License"
    },
    {
      "document_token": "D-15ZqBWNnbhbuEbjXdQP0",
      "timestamp": 1497377427997,
      "type": "passport",
      "name": "John Doe passport"
    }
  ],
  "reviews": [
    {
      "review_token": "R-Qdg9pmQAFGlIthI1R2AY",
      "outcome": "approved",
      "reason": "Documents received and validated",
      "application_name": "Customer Onboarding",
      "timestamp": 1497376799567,
      "reviewer": "john.doe@example.com"
    }
  ]
}

Entities are the center of the Alloy world. All evaluations, manual reviews, and documents are related to an entity whether or not you explicitly link them together in your API requests. This endpoint provides the ability to query on an entity and get top-level details about that entity as well as an overview of all items associated with the entity. The tokens from linked evaluations, reviews, or documents can be passed to their own API endpoints for more information about those specific items.

HTTP Request

GET https://sandbox.alloy.co/v1/entities/<entity_token>

Evaluations

Get An Evaluation

curl -X GET https://sandbox.alloy.co/v1/entities/<entity_token>/evaluations/<evaluation_token> \
  -H "Content-Type: application/json" \
  -u application_token:application_secret

If you want to look up the result of a previously-run evaluation, you can use the API to get the exact same response that was returned from POST /evaluations originally. Here is the endpoint for getting that information.

HTTP Request

GET https://sandbox.alloy.co/v1/entities/<entity_token>/evaluations/<evaluation_token>

Documents

Describe a Document Before Uploading

curl -X POST https://sandbox.alloy.co/v1/entities/<entity_token>/documents \
  -H "Content-Type: application/json" \
  -u application_token:application_secret \
  -d $'{
    "name": "driver_license",
    "extension": "pdf",
    "type": "license",
    "note": "Uploaded from email customer sent",
    "note_author_agent_email": "john.doe@example.com"
  }'

Or, if done before an entity is created:

curl -X POST https://sandbox.alloy.co/v1/documents \
  -H "Content-Type: application/json" \
  -u application_token:application_secret \
  -d $'{
    "name": "driver_license",
    "extension": "pdf",
    "type": "license",
    "note": "Uploaded from email customer sent",
    "note_author_agent_email": "john.doe@example.com"
  }'

If successful, the above command returns JSON structured like this:

{
  "document_token": "D-fu1WeoS2ywAROk1srtP9",
  "type": "license",
  "name": "driver_license",
  "extension": "pdf",
  "uploaded": false,
  "timestamp": 1497305164671,
  "approved": null,
  "approval_agent_email": null,
  "approval_timestamp": null,
  "notes": [
    {
      "note": "Uploaded from email customer sent",
      "note_author_agent_email": "john.doe@example.com",
      "created_at": 1497305164671,
      "updated_at": 1497305164671
    }
  ]
}

The document upload API is a two-step process. First, the metadata for the document is specified, and the API returns a file identifier so the file can be streamed directly to the next endpoint. You’ll need to look for the document_token returned in the response because that is necessary to pass to the next endpoint for streaming the file.

HTTP Request

POST https://sandbox.alloy.co/v1/entities/<entity_token>/documents

Query Parameters

Parameter Description Example
name* Name of the document to be uploaded driver_license
extension* File extension (JPG, PNG, PDF, etc.) pdf
type* Type of document (‘contract’, ‘license’, ‘passport’, or ‘utility’) license
note Description (optional) Uploaded from email
note_author_agent_email Email of agent to associate note with (optional but required if note is specified) john.doe@example.com

* required fields

Upload Document

curl -X PUT https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token> \
  -u application_token:application_secret
  <file stream>

If successful, the above command returns JSON structured like this:

{
  "document_token": "D-fu1WeoS2ywAROk1srtP9",
  "type": "license",
  "name": "driver_license",
  "extension": "pdf",
  "uploaded": true,
  "timestamp": 1497305164680,
  "approved": null,
  "approval_agent_email": null,
  "approval_timestamp": null,
  "notes": [
    {
      "note": "Uploaded from email customer sent",
      "note_author_agent_email": "john.doe@example.com",
      "created_at": 1497305164671,
      "updated_at": 1497305164671
    }
  ]
}

Now that that metadata for the file has been specified, you just need to stream the file to the location we’ve allocated for your file. The response should be the same as for the first endpoint except uploaded will be true.

HTTP Request

PUT https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token>

Update Document Metadata

curl -X PATCH https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token> \
  -u application_token:application_secret
  -d $'{
    "approved": true,
    "type": "passport",
    "approval_agent_email": "john.doe@example.com",
    "name": "new_name"
  }'

If successful, the above command returns JSON structured like this:

{
  "document_token": "D-fu1WeoS2ywAROk1srtP9",
  "type": "license",
  "name": "driver_license",
  "extension": "pdf",
  "uploaded": true,
  "timestamp": 1497305164680,
  "approved": true,
  "approval_agent_email": "john.doe@example.com",
  "approval_timestamp": 1497306624438,
  "notes": [
    {
      "note": "Uploaded from email customer sent",
      "note_author_agent_email": "john.doe@example.com",
      "created_at": 1497305164671,
      "updated_at": 1497305164671
    }
  ]
}

If you want to mark a document as “approved” or “denied” (if you have a document review process), or just change the name or type of a document, you can do so with the PATCH endpoint.

HTTP Request

PATCH https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token>

Query Parameters

Parameter Description Example
name Name of the document to be uploaded new_name_passport
type Type of document (‘contract’, ‘license’, ‘passport’, or ‘utility’) passport
approved Boolean approval (true or false) true
approval_agent_email Email of agent to associate approval with (optional but required if approval is specified) john.doe@example.com

Verifying Documents via Evaluations

An example of a cURL request using documents in an evaluation is below. Note that once you reference the documents in an API request, they will show up for that entity in the dashboard, and you will be able to view the images for the front and back of the driver’s license via the dashboard.

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Content-Type: application/json" \
  -u application_token:application_secret \
     -d $'{
       "name_first": "John",
       "name_last": "Doe",
       "document_token_front": "D-Y4vct54V523gj58sjJqv",
       "document_token_back": "D-BhyTecEZZ98Gdtyj3gb"
}'

If successful, the above command returns JSON structured like this:

{
  "document_token": "D-fu1WeoS2ywAROk1srtP9",
  "type": "license",
  "name": "driver_license",
  "extension": "pdf",
  "uploaded": true,
  "timestamp": 1497305164680,
  "approved": true,
  "approval_agent_email": "john.doe@example.com",
  "approval_timestamp": 1497306624438,
  "notes": [
    {
      "note": "Uploaded from email customer sent",
      "note_author_agent_email": "john.doe@example.com",
      "created_at": 1497305164671,
      "updated_at": 1497305164671
    }
  ]
}

Now that the images are uploaded, you can reference the documents in API calls.
For example, set up an application that contains a document verification service. These require a document_token_front and sometimes a document_token_back in order to perform ID verification.

Add Notes to a Document

curl -X POST https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token>/notes \
  -u application_token:application_secret
  -d $'{
    "note": "This document was approved by manual inspection",
    "note_author_agent_email": "john.doe@example.com"
  }'

If successful, the above command returns JSON structured like this:

{
  "document_token": "D-fu1WeoS2ywAROk1srtP9",
  "note": "This document was approved by manual inspection",
  "note_author_agent_email": "john.doe@example.com",
  "created_at": 1497302652999,
  "updated_at": 1497302652999
}

You can add an unlimited amount of notes to a document to keep track of whatever information is needed. All you need is to pass the note along with the email of the author of the note (must be a user associated with your customer account) to this API endpoint.

HTTP Request

POST https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token>/notes

Query Parameters

Parameter Description Example
note Any string you want “Document reviewed by John”
note_author_agent_email Email of agent to associate the note with (optional but required if approval is specified) john.doe@example.com

Get a List of All Documents for an Entity

curl -X GET https://sandbox.alloy.co/v1/entities/<entity_token>/documents \
  -u application_token:application_secret

If successful, the above command returns JSON structured like this:

[
  {
    "document_token": "D-nqMK4l4Ppxs3QaEEZVTL",
    "type": "license",
    "name": "John_license",
    "extension": "jpg",
    "uploaded": true,
    "timestamp": 1497294976617,
    "approved": null,
    "approval_agent_email": null,
    "approval_timestamp": null,
    "notes": [
      {
        "note": "Uploaded via web interface",
        "note_author_agent_email": "john.doe@example.com",
        "created_at": 1497294986800,
        "updated_at": 1497294986800
      }
    ]
  },
  {
    "document_token": "D-kn8sXlOgcEwTuUi5HVEU",
    "type": "utility",
    "name": "John_utility_bill",
    "extension": "pdf",
    "uploaded": true,
    "timestamp": 1497294520121,
    "approved": true,
    "approval_agent_email": "john.doe@example.com",
    "approval_timestamp": 1497294656014,
    "notes": [
      {
        "note": "Uploaded from email with customer",
        "note_author_agent_email": "john.doe@example.com",
        "created_at": 1497294656014,
        "updated_at": 1497294656014
      },
      {
        "note": "I've reviewed and approved this document",
        "note_author_agent_email": "john.doe@example.com",
        "created_at": 1497294664571,
        "updated_at": 1497294664571
      }
    ]
  }
]

All documents for an entity can be queried using this endpoint. All metadata for the documents is available, but the documents themselves must be downloaded individually.

HTTP Request

GET https://sandbox.alloy.co/v1/entities/<entity_token>/documents

Download a Document

curl -X GET https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token> \
  -u application_token:application_secret

If successful, the above command returns a file like this:

external link

This endpoint will return a file stream of the requested document.

HTTP Request

GET https://sandbox.alloy.co/v1/entities/<entity_token>/documents/<document_token>

Reviews

Get All Reviews for an Entity

curl -X GET https://sandbox.alloy.co/v1/entities/<entity_token>/reviews \
  -H "Content-Type: application/json" \
  -u application_token:application_secret

If successful, the above command returns JSON structured like this:

[
  {
    "review_token": "R-Qdg9pmQAFGlIthI1R2AY",
    "entity_token": "P-1OFFS4vGzxIEqe0WZd2m",
    "outcome": "approved",
    "reason": "Documents uploaded and approved",
    "application_name": "Customer Onboarding",
    "timestamp": 1497376799567,
    "reviewer": "john.doe@example.com",
    "notes": [
      {
        "note": "Document valid and information confirmed",
        "note_author_agent_email": "john.doe@example.com",
        "created_at": 1497376799677,
        "updated_at": 1497376799677
      }
    ]
  }
]

Reviews are created when an agent in the dashboard manually approves or denies an entity for an application. This is an endpoint to get that data.

HTTP Request

GET https://sandbox.alloy.co/v1/entities/<entity_token>/reviews

Get One Specific Review

curl -X GET https://sandbox.alloy.co/v1/entities/<entity_token>/reviews/<review_token> \
  -H "Content-Type: application/json" \
  -u application_token:application_secret

If successful, the above command returns JSON structured like this:

{
  "review_token": "R-Qdg9pmQAFGlIthI1R2AY",
  "entity_token": "P-1OFFS4vGzxIEqe0WZd2m",
  "outcome": "approved",
  "reason": "Documents uploaded and approved",
  "application_name": "Customer Onboarding",
  "timestamp": 1497376799567,
  "reviewer": "john.doe@example.com",
  "notes": [
    {
      "note": "Document valid and information confirmed",
      "note_author_agent_email": "john.doe@example.com",
      "created_at": 1497376799677,
      "updated_at": 1497376799677
    }
  ]
}

Sometimes you need to get a specific review, here is how to do it.

HTTP Request

GET https://sandbox.alloy.co/v1/entities/<entity_token>/reviews/<review_token>

Other Useful API Tricks

Linking a New Evaluation to an Existing Entity

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Content-Type: application/json" \
  -u application_token:application_secret \
  -H "Alloy-Entity-Token: E-lCJeGUO7NGLC52BisUJP" \
  -d $'{
    "name_first": "John",
    ...
  }'

Passing an entity token in the header of a request will link any new evaluation to that existing entity. An example of this in action can be seen to the right.

Refreshing the cache

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Alloy-Refresh-Cache: true" \
  ...

All requests try to use cached service output as much as possible. If the input to an upstream service is exactly the same as we have seen in the past and the configurations for that service are also the same, we will get the result out of the cache if possible. To override this functionality, just pass Alloy-Refresh-Cache: true as a header for each request and the cache will be bypassed.

Bypassing automatic formatting

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Alloy-Bypass-Formatter: true" \
  ...

All request attributes are formatted to make matching easier across services. Sometimes this results in unexpected or unwanted behavior. For instance, the address may be legitimate, but our formatter does not recognize it and changes it to a similar address. In this case, you can bypass the formatter by specifying a header in the request.

Specifying an application version

curl -X POST https://sandbox.alloy.co/v1/evaluations \
  -H "Alloy-Application-Version: 108" \
  ...

By default the API uses the “pinned” application version from the dashboard. This can be overridden however by passing the Alloy-Application-Version header with the version ID of the desired application version.

Errors

Error Format

All errors will return with the same base format. Look to the right to see an example.

{
  "status_code": 401,
  "error": {
    "minor_code": 4012,
    "type": "API Authentication Failure",
    "message": "The supplied bearer token has expired.  Please obtain a new one.",
    "details": {
      "bearer_token": "7GimeNYhwD3fs0xoTtLXdZIox53eSttzrRf71ENA"
    },
    "error_token": "54ae20da-a2d3-47a1-ac29-f9b7569ca652"
  },
  "timestamp": 1472052254031,
  "evaluation_token": null,
  "entity_token": null,
  "application_token": null,
  "application_version_id": null
}
Attribute Description
status_code Same as HTTP status code but included for easy access and debugging
error The main error object
error.minor_code Minor code indicating the exact type of the error. Every type of handled error in the Alloy system gets a unique minor error code. See below for the list of possible minor error codes
error.type High level description of error
error.message More detailed error message
error.details Object possibly containing information to make it easier to debug the cause of the error
timestamp Unix timestamp of error
evaluation_token Evaluation token for this request if it has been set (otherwise null)
entity_token Entity token for this request if it has been set (otherwise null)
application_token Application token for this request if it has been set (otherwise null)
application_version_id Application version ID for this request if it has been set (otherwise null)
HTTP code Minor Code Description
200 Success - Everything worked perfectly
201 Created - this will be the result of all HTTP POST requests, we just successfully “created” the entity on our system
206 Partial Response - if the request executed but some upstream services failed to execute, we will return as much data as we can. You can resume this evaluation where it left off by running POST https://sandbox.alloy.co/v1/evaluations/<evaluation_token>
400 4001 Bad Request - Header Validation Failure
400 4002 Bad Request - Request Body Validation Failure
400 4003 Bad Request - Invalid Request Body
401 4011 Unauthorized
401 4012 Unauthorized - Credentials Expired
401 4013 Unauthorized - API Authentication Failure
401 4014 Unauthorized - Bearer token refresh unauthorized
401 4015 Unauthorized - Production mode disabled
403 4031 Forbidden - Entity token not valid
403 4032 Forbidden - Environment mismatch - can not switch between sandbox and live
404 4041 Not Found - Evaluation Not Found
409 4091 Conflict - Evaluation already resolved
412 4121 Precondition Failed - App disabled
418 4180 I’m a teapot
500 5000 Unhanded Server Error
500 5001 Unhanded Server Error - Service(s) disabled
500 5002 Unhanded Server Error - Response body validation failure
503 5031 Service Unavailable - We’re temporarily offline for maintenance. We’re probably looking over Peter’s shoulder while he configures NGINX.