Credit Builder as a Service API-First Documentation

Please note: If your company is integrating our Credit Builder as a Service product using only our APIs, you’re in the right spot!

Environments

There are two types of environments for the Upward Credit Suite:

  1. Sandbox
    You can test out your integration and explore common usage patterns in our sandbox environment. This environment is fully isolated and will not perform any “live” financial transactions.

You can request sandbox access once you have a signed contract.

Important: The Sandbox environment is fully secure, but you should not store any real consumer data here.

  1. Production
    Once you have completed sandbox testing and submitted your test plans, you will be provisioned production access keys. These details will be shared with you via a secure sharing mechanism. All transactions in our production environment are live financial activity.

Authentication

Upward’s API uses OAuth 2.0 to authenticate requests. All API calls must include a token. These authentication tokens are used for machine to machine communication.

Note: An invalid, missing or expired token will result in an {invalid_token} response

URLs

Environment URL Sandbox Authentication https://auth-sandbox.upwardli.com/auth/token

Production Authentication https://auth.upwardli.com/auth/token

Exchanging Partner API Token for a Customer Token

Once a valid token has been obtained using the Authentication API, a limited scope token can be obtained using the token exchange API. This token can be used to make requests for a specific consumer, and is safe to send to the client application/web browser as needed.

To request a token exchange send a POST to our auth server containing the access_token and requested scope.

This token expires after 1 hour and will need to be exchanged for a new token for the customer to continue to have access.

Notes:

  • The audience must be for the correct Environment.
    • Sandbox: https://auth-sandbox.upwardli.com
    • Production: https://auth.upwardli.com
  • The upward_consumer_id is the Upward id that you get from the Consumer API or the consumer.created webhook.
  • The new access token is a significantly longer string than the original access token.

POST https://auth-sandbox.upwardli.com/auth/token/exchange/

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}
5Body
6{
7    "grant_type":"urn:ietf:params:oauth:grant-type:token-exchange",
8    "subject_token_type":"urn:ietf:params:oauth:token-type:access_token",
9    "subject_token":"[access_token]",
10    "audience":"https://auth-sandbox.upwardli.com",
11    "scope":"<See scopes table> consumer:[upward_consumer_id]"
12}

Here’s what a successful response looks like:

1{
2  "token_type": "Bearer",
3  "expires_in": 3600,
4  "access_token": "[scoped access token]",
5  "scope": "<Scope(s)>",
6  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
7}

API Onboarding Flow Specifics

  1. Create Consumer
  2. Create Onboarding
  3. Verify the Consumer’s Identity (KYC)
  4. Provide Underwriting decision
  5. Accept Terms
  6. Submit Loan

Step 1: Create Consumer

Partners must create a consumer via the Create Consumer API before creating the onboarding.

Step 2: Create Onboarding

To start the onboarding workflow for a user, you post a message containing the pcid of the consumer and an onboarding_template_id value of cbaas_onboarding. The API will return a partially hydrated onboarding object containing the consumer’s current onboarding state.

POST https://api-sandbox.upwardli.com/v2/onboarding/

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}

Body

1{
2  "pcid": "{consumer pcid}",
3  "onboarding_template_id": "cbaas_onboarding"
4}

Response

1{
2    "id": "6a822b8a-0423-4ae7-bad6-02e09adab632",
3    "consumer": {
4		    "id": "bce4e19c-69fe-4af0-8ff7-6652f7265018",
5		    "pcid": "8d397680-deb1-44fe-a6fa-7454e8843fb7",
6		    "first_name": "John",
7		    "last_name": "Doe",
8		    "email": "john.doe@email.com",
9		    "is_active": true,
10		    "kyc_status": "Complete",
11		    "phone_number": "425-555-1212",
12		    "date_of_birth": "1999-10-06",
13		    "tax_id_type": "SSN",
14		    "tax_identifier": "***-**-6789",
15		    "address_line1": "121 Big Creek",
16		    "address_line2": null,
17		    "address_city": "Tuscaloosa",
18		    "address_state": "AL",
19		    "address_zip": "354050000"
20    },
21    "kyc": {
22        "inquiry_template_id": null
23        "inquiry_ids": null
24    },
25    "e_sign": {
26        "agreement_accepted": null,
27        "agreement_accepted_date": null
28    },
29    "product": {
30        "product_id": null
31    },
32    "underwriting": {
33      "result": null,
34      "data": null
35    },
36    "previous_step": {
37        "slug": "get_started",
38    },
39    "current_step": {
40        "slug": "verify_identity",
41    }
42}

Step 3: Verify the Consumer’s Identity (KYC)

Each consumer will see an entry screen that will highlight the value props and also include the appropriate disclaimers for the product.

POST https://api-sandbox.upwardli.com/v2/onboarding/{onboarding_id}/verify_identity

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}

Response

1{
2    "id": "6a822b8a-0423-4ae7-bad6-02e09adab632",
3    "consumer": {
4		    "id": "bce4e19c-69fe-4af0-8ff7-6652f7265018",
5		    "pcid": "8d397680-deb1-44fe-a6fa-7454e8843fb7",
6		    "first_name": "John",
7		    "last_name": "Doe",
8		    "email": "john.doe@email.com",
9		    "is_active": true,
10		    "kyc_status": "Complete",
11		    "phone_number": "425-555-1212",
12		    "date_of_birth": "1999-10-06",
13		    "tax_id_type": "SSN",
14		    "tax_identifier": "***-**-6789",
15		    "address_line1": "121 Big Creek",
16		    "address_line2": null,
17		    "address_city": "Tuscaloosa",
18		    "address_state": "AL",
19		    "address_zip": "354050000"
20    },
21    "kyc": {
22        "inquiry_template_id": null
23        "inquiry_ids": [
24            "inq_be55e136-2ca9-4f20-b262-4a1004f27e2e",
25            "inq_bd77c402-b95b-4d58-8104-9652a25bc1e9"
26        ]
27    },
28    "e_sign": {
29        "agreement_accepted": null,
30        "agreement_accepted_date": null
31    },
32    "product": {
33        "product_id": null
34    },
35    "underwriting": {
36      "result": null,
37      "data": null
38    },
39    "previous_step": {
40        "slug": "get_started",
41    },
42    "current_step": {
43        "slug": "accept_terms",
44    }
45}

Step 4: Provide Underwriting Decision

POST https://api-sandbox.upwardli.com/v2/onboarding/{onboarding_id}/perform-underwriting

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}

Body

1{
2  "result": "pass|fail",
3  "data": "{}"
4}

Response

1{
2    "id": "6a822b8a-0423-4ae7-bad6-02e09adab632",
3    "consumer": {
4		    "id": "bce4e19c-69fe-4af0-8ff7-6652f7265018",
5		    "pcid": "8d397680-deb1-44fe-a6fa-7454e8843fb7",
6		    "first_name": "John",
7		    "last_name": "Doe",
8		    "email": "john.doe@email.com",
9		    "is_active": true,
10		    "kyc_status": "Complete",
11		    "phone_number": "425-555-1212",
12		    "date_of_birth": "1999-10-06",
13		    "tax_id_type": "SSN",
14		    "tax_identifier": "***-**-6789",
15		    "address_line1": "121 Big Creek",
16		    "address_line2": null,
17		    "address_city": "Tuscaloosa",
18		    "address_state": "AL",
19		    "address_zip": "354050000"
20    },
21    "kyc": {
22        "inquiry_template_id": null
23        "inquiry_ids": [
24            "inq_be55e136-2ca9-4f20-b262-4a1004f27e2e",
25            "inq_bd77c402-b95b-4d58-8104-9652a25bc1e9"
26        ]
27    },
28    "e_sign": {
29        "agreement_accepted": null,
30        "agreement_accepted_date": null
31    },
32    "product": {
33        "product_id": null
34    },
35    "underwriting": {
36      "result": "pass",
37      "data": "{\"key_1\":\"value_1\",\"key_2\":\"value_2\}"
38    },
39    "previous_step": {
40        "slug": "get_started",
41    },
42    "current_step": {
43        "slug": "accept_terms",
44    }
45}

Step 5: Accept Terms

Once a user has accepted the terms of their loan + CBAAS agreements, you can update their onboarding workflow to reflect the date/time that the agreements were accepted.

POST https://api-sandbox.upwardli.com/v2/onboarding/{onboarding_id}/accept-terms/

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}

Body

1{
2  "agreement_accepted": true
3}

Response

1{
2    "id": "6a822b8a-0423-4ae7-bad6-02e09adab632",
3    "consumer": {
4		    "id": "bce4e19c-69fe-4af0-8ff7-6652f7265018",
5		    "pcid": "8d397680-deb1-44fe-a6fa-7454e8843fb7",
6		    "first_name": "John",
7		    "last_name": "Doe",
8		    "email": "john.doe@email.com",
9		    "is_active": true,
10		    "kyc_status": "Complete",
11		    "phone_number": "425-555-1212",
12		    "date_of_birth": "1999-10-06",
13		    "tax_id_type": "SSN",
14		    "tax_identifier": "***-**-6789",
15		    "address_line1": "121 Big Creek",
16		    "address_line2": null,
17		    "address_city": "Tuscaloosa",
18		    "address_state": "AL",
19		    "address_zip": "354050000"
20    },
21    "kyc": {
22        "inquiry_template_id": null
23        "inquiry_ids": [
24            "inq_be55e136-2ca9-4f20-b262-4a1004f27e2e",
25            "inq_bd77c402-b95b-4d58-8104-9652a25bc1e9"
26        ]
27    },
28    "e_sign": {
29        "agreement_accepted": true,
30		    "agreement_accepted_date": "2025-05-11T14:47:56.152870Z"
31    },
32    "product": {
33        "product_id": "95630f7a-dc51-4c61-914b-14c26b99968c"
34    },
35    "underwriting": {
36      "result": "pass",
37      "data": "{\"key_1\":\"value_1\",\"key_2\":\"value_2\}"
38    },
39    "previous_step": {
40        "slug": "get_started",
41    },
42    "current_step": {
43        "slug": "accept_terms",
44    }
45}

Step 6: Submit Loan

Once a user has accepted the terms of their loan + CBAAS agreements, you are ready to submit their loan data. This step will also begin to provision their credit line.

POST https://api-sandbox.upwardli.com/v2/onboarding/{onboarding_id}/submit-loan/

1Header
2{
3    "Authorization":"Bearer [access_token]"
4}

Response

1{
2    "id": "6a822b8a-0423-4ae7-bad6-02e09adab632",
3    "consumer": {
4		    "id": "bce4e19c-69fe-4af0-8ff7-6652f7265018",
5		    "pcid": "8d397680-deb1-44fe-a6fa-7454e8843fb7",
6		    "first_name": "John",
7		    "last_name": "Doe",
8		    "email": "john.doe@email.com",
9		    "is_active": true,
10		    "kyc_status": "Complete",
11		    "phone_number": "425-555-1212",
12		    "date_of_birth": "1999-10-06",
13		    "tax_id_type": "SSN",
14		    "tax_identifier": "***-**-6789",
15		    "address_line1": "121 Big Creek",
16		    "address_line2": null,
17		    "address_city": "Tuscaloosa",
18		    "address_state": "AL",
19		    "address_zip": "354050000"
20    },
21    "kyc": {
22        "inquiry_template_id": null
23        "inquiry_ids": [
24            "inq_be55e136-2ca9-4f20-b262-4a1004f27e2e",
25            "inq_bd77c402-b95b-4d58-8104-9652a25bc1e9"
26        ]
27    },
28    "e_sign": {
29        "agreement_accepted": true,
30		    "agreement_accepted_date": "2025-05-11T14:47:56.152870Z"
31    },
32    "product": {
33        "product_id": "95630f7a-dc51-4c61-914b-14c26b99968c"
34    },
35    "underwriting": {
36      "result": "pass",
37      "data": "{\"key_1\":\"value_1\",\"key_2\":\"value_2\}"
38    },
39    "previous_steps": [
40        {
41            "slug": "perform_underwriting"
42        },
43        {
44            "slug": "select_product"
45        },
46        {
47            "slug": "accept_terms"
48        },
49        {
50            "slug": "verify_identity"
51        },
52        {
53            "slug": "get_started"
54        }
55    ],
56    "current_steps": null
57}