Cove API Screening Quickstart

Introduction

The Cove API enables easy screening of users. This guide provides a detailed walkthrough of how to use the API, from setting up your account to conducting applicant screenings.

Base URL

https://sandbox-api.cove.dev

Detailed Workflow

To begin using the Cove API, you need login credentials. Send an email to team@cove.dev requesting access to your account and the dashboard. Once you receive your credentials, you can authenticate and start making API calls.

Step 2: Authenticate

Before accessing other endpoints, you must authenticate using the /v1/auth/login endpoint to obtain an access token.

Endpoint

POST /v1/auth/login

Description

This endpoint validates your username and password. If successful, it returns an accessToken that you must include in all subsequent API calls.

Request Headers

Content-Type: application/json
Accept: application/json

Request Body

{
  "username": "<string>",
  "password": "<string>"
}

Example

curl -X POST https://sandbox-api.cove.dev/v1/auth/login \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "username": "your-username",
  "password": "your-password"
}'

Success (200):
{ "accessToken": "<string>" }
Error (401): Unauthorized.

Usage of Token

Include the accessToken in the Authorization header for all subsequent requests:

Authorization: <accessToken>

Step 3: Setup a Flow

Before you can create a screening, you need to setup a flow. You can do this in the dashboard (https://sandbox.cove.dev/). Remember: Flows allow you to create custom screening processes tailored to your specific needs. Instead of using predefined checks, you can define a sequence of steps and reuse them across multiple screenings. Once you have created a flow, note the flowID. You will use it in the next step.

Step 4: Send Screening Link

You can initiate a screening process by sending a link to the applicant. Use the /v2/screening/send endpoint for this.

Endpoint

POST /v2/screening/send

Description

Generates and sends a screening link to the applicant, enabling them to complete the screening process.

Headers

Authorization: <API Key>
Content-Type: application/json
Accept: application/json

Request Body

{
  "flowId": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "metadata": {
    "customKey": "<any>"
  },
  "options": {
    "emailDisabled": "<boolean>",
    "smsDisabled": "<boolean>"
  },
  "payer": "PAYER_SELF"
}

Example

curl -X POST https://sandbox-api.cove.dev/v2/screening/send \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "flowId": "flow-id-from-previous-step",
  "email": "applicant@example.com",
  "phone": "+14160001111",
  "firstName": "John",
  "lastName": "Doe",
  "metadata": {
    "customKey": "customValue"
  },
  "options": {
    "emailDisabled": false,
    "smsDisabled": false
  },
  "payer": "PAYER_SELF"
}'

Success (200):

{
  "message": "<string>",
  "userId": "<string>",
  "screeningId": "<string>",
  "screeningLink": "<string>"
}

Notes

Provide accurate applicant information to ensure the screening link reaches the right individual.
The screeningId from this response will be required for retrieving the screening results or for other requests related to the screening.
If you set emailDisabled to true, the applicant will not receive an email. If you set smsDisabled to true, the applicant will not receive an SMS. You will be responsible for sharing the screeningLink with the applicant.

Step 5: Generate an iFrame for the Screening (Optional)

If you prefer to embed the screening process directly into your application, you can generate an iFrame for the screening link. Use the screeningLink obtained from the previous step to create an iFrame. It will go in the src attribute of the iFrame.

Example

<iframe 
  title="Cove Embed"
  id="cove-embed"
  allow="camera; microphone; accelerometer"
  sandbox="allow-scripts allow-same-origin allow-forms"
  height="800"
  width="100%"
  src="{url}" 
></iframe>

<script>
  // For security, verify the origin
  if (
    event.origin !== 'https://app.cove.dev' &&
    event.origin !== 'https://sandbox.cove.dev' &&
    event.origin !== 'http://localhost:3000' &&
    event.origin !== 'http://localhost:3001'
  ) {
    return;
  }

  window.addEventListener('message', function(event) {
    const coveEmbed = document.getElementById('cove-embed');
    coveEmbed?.contentWindow?.postMessage(event.data, "*");

    // For security, verify the origin
    if (
      event.origin !== 'https://app.cove.dev' &&
      event.origin !== 'https://sandbox.cove.dev' &&
      event.origin !== 'http://localhost:3000'
    ) {
      return;
    }

    if (
      event.data.source === "cove-embed" &&
      event.data.status === "USER_COMPLETE"
    ) {
      console.log("message:", event.data);
      coveEmbed.remove();
    }
  });
</script>

Step 6: Get Screening Results

There are two ways to get screening results. You can either retrieve the raw screening data or you can retrieve a PDF report of the screening. You can also do both. The raw data is useful for programmatic access, while the PDF report is useful for sharing with stakeholders or for record-keeping.

Step 6.1: Retrieve Screening Data
Step 6.2: Retrieve Screening Report PDF

Step 6.1: Retrieve Screening Data

Once the applicant completes the screening, you can fetch their results using the /v2/screening/:screeningId endpoint.

Endpoint

GET /v2/screening/:screeningId

Description

Retrieves detailed screening results for a specific session.

Headers

Authorization: <API Key>
Accept: application/json

URL Parameters

screeningId: (Required) Unique identifier for the session.

Example

curl -X GET https://sandbox-api.cove.dev/v2/screening/<screeningId> \
-H "Authorization: your-access-token" \
-H "Accept: application/json"

Success (200):

{
  "user": "<string>",
  "flowId": "<string>",
  "metadata": { ... },
  "screeningSteps": { ... },
  "data": { ... }
}

Notes

Use this endpoint to evaluate the applicant’s suitability based on their screening data.

Step 6.2: Retrieve Screening Report PDF

Once the applicant completes the screening, you can also fetch their results as a PDF report using the /v2/screening/:screeningId/report endpoint.

Endpoint

GET /v2/screening/:screeningId/report

Description

Retrieves detailed screening results for a specific session as a PDF report.

Headers

Authorization: <API Key>
Accept: application/json

URL Parameters

screeningId: (Required) Unique identifier for the session.

Example

curl -X GET https://sandbox-api.cove.dev/v2/screening/<screeningId>/report \
-H "Authorization: your-access-token" \
-H "Accept: application/json"

Success (200):
{ "url": "<string>" }

Notes

Use this endpoint to evaluate the applicant’s suitability based on their screening data.

Step 7: Run Manual Credit Check (If Applicable)

If an applicant’s credit check was not successful after they’ve completed the screening application, or if you are using your own consent form and application and are not using other nodes in the flow, you can run a credit check for the applicant yourself.

Step 7.1: Add Data for Credit Check
Step 7.2: Run the Credit Check

Step 7.1: Add Data for Credit Check

Before running a credit check, you must add the applicant’s data to their account.

POST /v1/user/:userId

Description

Update user’s information for the screening.

Headers

Authorization: <API Key>
Content-Type: application/json
Accept: application/json

Request Body

{
  "firstName": "<string>",
  "lastName": "<string>",
  "address": {
    "street": "<string>",
    "city": "<string>",
    "provinceState": "<string>",
    "country": "<string>",
    "postalCode": "<string>"
  },
  "sin": "<string>",
  "dateOfBirth": "<string>"
}

Example

curl -X POST https://sandbox-api.cove.dev/v1/user/<userId> \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "firstName": "John",
  "lastName": "Doe",
  "address": {
    "street": "123 Main St",
    "city": "Toronto",
    "provinceState": "ON",
    "country": "Canada",
    "postalCode": "M5H 2N2"
  },
  "sin": "123-456-789",
  "dateOfBirth": "1990-01-01"
}'

Success (200):

{
  "message": "<string>",
  "userId": "<string>"
}

Notes

Ensure that the userId corresponds to the applicant you are screening.

Step 7.2: Run the Credit Check

Once the applicant’s data is added, run the credit check.

POST /v2/screening/run

Description

Run the screening for the applicant using the provided user data.

Headers

Authorization: <API Key>
Content-Type: application/json
Accept: application/json

Request Body

{
  "screeningId": "<string>"
}

Example

curl -X POST https://sandbox-api.cove.dev/v2/screening/run \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "screeningId": "screening-id-from-earlier-step"
}'

Success (200):

{
  "message": "<string>",
  "userId": "<string>",
  "screeningId": "<string>"
}

Notes

You are responsible for ensuring compliance with consent laws when running a credit check yourself.

Step 8: Re-send a Specific Screening Step (If Skipped)

If an applicant skipped a step (e.g., bank verification) or needs to re-complete a part of the screening, you can re-send the screening link for that specific step using the /v2/screening/resend-step endpoint.

Endpoint

POST /v2/screening/resend-step

Description

Re-sends the screening link for a specific step in the flow to the applicant. This is helpful if a step was skipped or needs to be redone (e.g., FINANCIAL_VERIFICATION).

Headers

Authorization: <API Key>
Content-Type: application/json
Accept: application/json

Request Body

{
  "screeningId": "<string>",
  "skippedStepName": "<string>", 
  "options": {
    "emailDisabled": "<boolean>",
    "smsDisabled": "<boolean>"
  }
}

Example

curl -X POST https://sandbox-api.cove.dev/v2/screening/resend-step \
-H "Authorization: Bearer your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "screeningId": "your-screening-id",
  "skippedStepName": "FINANCIAL_VERIFICATION",
  "options": {
    "emailDisabled": true,
    "smsDisabled": true
  }
}'

Success (200):

{
  "message": "Flow screening sent successfully",
  "user_id": "6830d7964f5de74a4e600869",
  "retry_link": "https://sandbox.cove.dev/s/6830d7964f5de74a4e60086b?resent=FINANCIAL_VERIFICATION&login-code=abc123&email=user%40example.com"
}

Notes

The retry_link can be used to direct the applicant to the specific step that was skipped.
Valid values for skippedStepName include FINANCIAL_VERIFICATION, ID_VERIFICATION, EMPLOYMENT, CREDIT_CHECK, RESIDENCE_HISTORY, CUSTOM_FORM, and PERSONAL_INFO with more being added in the future.
This feature is particularly useful when an applicant abandons the process or encounters an issue with a specific step.

Additional Information

All endpoints require HTTPS communication.
Errors are returned in JSON format with appropriate HTTP status codes.
For detailed documentation, visit the Cove API Docs.

Need Help?

For further assistance, contact team@cove.dev.

​Cove API Screening Quickstart

​Introduction

​Base URL

​Detailed Workflow

​Step 1: Request Login Credentials

​Step 2: Authenticate

​Endpoint

​Description

​Request Headers

​Request Body

​Example

​Usage of Token

​Step 3: Setup a Flow

​Step 4: Send Screening Link

​Endpoint

​Description

​Headers

​Request Body

​Example

​Notes

​Step 5: Generate an iFrame for the Screening (Optional)

​Example

​Step 6: Get Screening Results

​Step 6.1: Retrieve Screening Data

​Endpoint

​Description

​Headers

​URL Parameters

​Example

​Notes

​Step 6.2: Retrieve Screening Report PDF

​Endpoint

​Description

​Headers

​URL Parameters

​Example

​Notes

​Step 7: Run Manual Credit Check (If Applicable)

​Step 7.1: Add Data for Credit Check

​Description

​Headers

​Request Body

​Example

​Notes

​Step 7.2: Run the Credit Check

​Description

​Headers

​Request Body

​Example

​Notes

​Step 8: Re-send a Specific Screening Step (If Skipped)

​Endpoint

​Description

​Headers

​Request Body

​Example

​Notes

​Additional Information

​Need Help?

Cove API Screening Quickstart

Introduction

Base URL

Detailed Workflow

Step 1: Request Login Credentials

Step 2: Authenticate

Endpoint

Description

Request Headers

Request Body

Example

Usage of Token

Step 3: Setup a Flow

Step 4: Send Screening Link

Endpoint

Description

Headers

Request Body

Example

Notes

Step 5: Generate an iFrame for the Screening (Optional)

Example

Step 6: Get Screening Results

Step 6.1: Retrieve Screening Data

Endpoint

Description

Headers

URL Parameters

Example

Notes

Step 6.2: Retrieve Screening Report PDF

Endpoint

Description

Headers

URL Parameters

Example

Notes

Step 7: Run Manual Credit Check (If Applicable)

Step 7.1: Add Data for Credit Check

Description

Headers

Request Body

Example

Notes

Step 7.2: Run the Credit Check

Description

Headers

Request Body

Example

Notes

Step 8: Re-send a Specific Screening Step (If Skipped)

Endpoint

Description

Headers

Request Body

Example

Notes

Additional Information

Need Help?