Getting Started

About

A postman collection can be provided upon request with the Bloom Enablement Services endpoints (HTTP and GraphQL), as well as the Plaid Sandbox endpoints needed for this guide.

Reference

Plaid - An aggregator. An aggregator handles creating connections to financial institutions and retrieving information about those connections like bank accounts and transactions.

Prerequisites

Completed Bloom onboarding process.
Create a Plaid account. If you wish to use a different aggregator, contact Bloom support.

Getting Started

Obtain a Client ID and Client Secret for Authentication from Bloom onboarding process. You will also need your organization's slug, obtained during this process as well.

Create a user using the RegisterOrganizationUser GraphQL Mutation, with you user's information and the organization slug obtained above. Optionally, check if a user exists with the email by using the UserExistsWithEmail GraphQL Query.

Grab the correct GraphQL URL from the What URL Should I be Using . Use this URL for all following operations.
Authenticate by providing the Client ID and Client Secret obtained in step 1 as a bearer token header. This step requires organization scoped authentication (see Enablement Services Authentication).
```
Authorization: Bearer client_id:client_secret
```

Run the mutation:

mutation RegisterOrganizationUser {
    registerOrganizationUser(
        input: {
            organizationSlug: "bloom"
            email: "[email protected]"
            phoneNumber: "+12345678901"
            name: { first: "Buzz", last: "Inga" }
            address: {
                line1: "123 Main "
                city: "Athens"
                state: "FL"
                country: "USA"
                zipcode: "37745"
                type: PRIMARY
            }
            dateOfBirth: { day: 14, month: 6, year: 1986 }
            nationalId: "1234"
        }
    ) {
        user {
            id
            name {
                first
                middle
                last
            }
        }
    }
}

Hold on to the user id in the response.

Call the /v1/users/authenticate/{{user_id}} HTTP endpoint. Use the API URL, not the GraphQL URL, from What URL Should I Be Using?. Replace {{user_id}} with the user id from the previous step. The body returned will be the session token.
1. This token is valid for 2 hours. When it expires, simply grab another one with this endpoint.
2. There may be a slight delay of no more than 30 seconds between user creation, and when authentication can be performed.
3. Use organization scoped authentication, just as in the previous step.

curl --location --request POST 'https://api.bloomplus.dev/v1/users/authenticate/{{user_id}}' \
--header 'Authorization: Bearer {{client_id}}:{{client_secret}}'

From here on out, use the session token obtained in step 3 for authentication unless otherwise stated. Provide the token as a bearer token provided in the headers. This is referred to as user scoped authentication (see Enablement Services Authentication). Replace session_token with your session token (no quotes).
```
Authorization: Bearer session_token
```

Check that you are able to query the newly created user with the Me GraphQL query. Make sure you are using the session token for authentication.

query Me {
    me {
        id
        email
        phoneNumber
        status
        notificationPreferences
        createdAt
        updatedAt
        syncedAt
        closedAt
        name {
            first
            middle
            last
        }
    }
}

Obtain a connection token from Plaid.
1. For sandbox, see Getting Plaid Sandbox Token
Use the ImportConnection Mutation to import a connection. Replace the token with the Plaid connection token. This will start a workflow to ingest the Plaid user's transactions into the Bloom Enablement Services.
```
mutation ImportConnection {
    importConnection(token: "access-sandbox-faa83ce0-7bb4-4baa-a824-b746d5c99f28") {
        provider
        connectionId
    }
}
```
Check that the user's transactions have been imported. These will be listed under the tradelines for the user in the Me query, once the ingestion process is completed. The trasanction ingestion is complete when the query shows the user's tradelines. A sample query is listed below, showing the first 5 tradelines for the user.
1. In sandbox, this takes about 5 minutes.
2. Tradelines will be listed as eligible or ineligible via the isEligible property. Eligible tradelines can be imported in the next step.
3. In the response, the tradeline ID's will be under tradelines > edges > node > id for each tradeline.

query Me {
    me {
        tradelines(input: { first: 5 }) {
            edges {
                cursor
                node {
                    id
                    merchant
                    category
                    isOpen
                    isEligible
                    paymentFrequency
                    serviceAddress
                    servicePhone
                    leaseStartDate
                    utilityTypes
                    serviceAddressType
                    createdAt
                    updatedAt
                    transactions(input: { first: 5 }) {
                        edges {
                            cursor
                            node {
                                id
                                date
                                value {
                                    amount
                                    currency
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Open a tradeline to be reported with the OpenTradeline Mutation. The tradeline ID is obtained in the previous step. Only use an eligible tradeline. For example, to import a Rent tradeline:

mutation OpenTradeline {
    openTradeline(
        input: {
            servicePhone: "1234567890"
            serviceAddressType: PRIMARY
            leaseStartDate: "2025-01-01"
            agreements: {
                rent: { isPrimaryAddress: true, hasOtherMortgageOrRent: false }
            }
            tradelineId: "0195d95a-314e-7d42-9baf-862f83354110"
        }
    ) {
        attestation {
            agreements {
                rent {
                    isPrimaryAddress
                    hasOtherMortgageOrRent
                }
            }
        }
    }
}

Upon importing a tradeline with the above mutation, Bloom Enablement Services will ingest the transactions from the aggregator. To verify that your tradeline has been successfully opened, use the Me query again. The imported tradeline should be listed with the isOpen property set to true. Your data is now ready to be furnished!

Closing a Tradeline

If you wish to close a tradeline, use the CloseTradeline Mutation. All that is required is the tradeline ID, which can be found with the Me query. This mutation requires a session token, as per User Scoped Authentication. Following the example in Getting Started , the mutation may look like:

mutation CloseTradeline {
    closeTradeline(id: "0195d95a-314e-7d42-9baf-862f83354110") {
        tradeline {
            id
            merchant
            category
            isOpen
            isEligible
            paymentFrequency
            serviceAddress
            servicePhone
            leaseStartDate
            utilityTypes
            serviceAddressType
            createdAt
            updatedAt
        }
    }
}

This will start a workflow in the Bloom Enablement Services to ensure the tradeline will not be furnished.
The status of a closed tradeline can be checked with the Me query. The tradeline should now show as "isOpen": false, and isEligible: false.

Delete a User

If you wish to delete a user, use the DeleteMe mutation. Use the user's session token, mentioned in User Scoped Authentication.

What URL Should I Be Using

For sandbox environments:
- API: https://api.blomplus.dev/gql
- GraphQL: https://api.bloomplus.dev
For production environments:
- API: https://api.bloomplus.com
- GraphQL: https://gql.bloomplus.com

Getting Plaid Sandbox Token

Plaid provides a custom user sandbox that can be used to create test users with test data for accounts and transactions. For detailed information, see the Plaid Documentation . These endpoints are also available in the Bloom Enablement Services Postman collection.

Create a sandbox user in the Plaid UI. The video provided in the first link gives a good overview. Once you create a plaid account, create a test user in the Plaid UI under Developers > Sandbox page . Hold on to the username for the next step. Obtain the Plaid client ID and secret from the Developers > Keys page .
Get a Plaid Sandbox Token via the plaid API. The institution ID is arbitrary for sandbox. Replace plaid_client_id and plaid_client_secret with your Plaid keys, and custom_username with your test user's username. Hang on the to public_token returned in the response. Make sure to include the identity and transactions products as shown below.

curl --location 'https://sandbox.plaid.com/sandbox/public_token/create' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "plaid_client_id",
    "secret": "plaid_client_secret",
    "institution_id": "ins_20",
    "initial_products": ["identity", "transactions"],
    "options": {
        "override_username": "custom_username"
    }
}'

Exchange the plaid sandbox token for an access token. Replace plaid_client_id and plaid_client_secret with your Plaid keys, and plaid_sandbox_token with your plaid public_token. Hold on to the access_token in the response.

curl --location 'https://sandbox.plaid.com/item/public_token/exchange' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "plaid_client_id",
    "secret": "plaid_client_secret",
    "public_token": "plaid_sandbox_token"
}'

To test that your token worked, query the get accounts endpoint. This should correspond to the test data you provided your test user in step 1. Replace plaid_client_id and plaid_client_secret with your Plaid keys, and plaid_access_token with your plaid access_token.

curl --location 'https://sandbox.plaid.com/accounts/get' \
--header 'Content-Type: application/json' \
--data '{
    "client_id": "plaid_client_id",
    "secret": "plaid_client_secret",
    "access_token": "plaid_access_token"
}'