Getting Started

About

This guide provides instructions to create a user in Bloom Enablement Services, and the steps necessary to import that user's tradelines for furnishing. Also included are instructions for closing a user's tradeline, and deleting a user.

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

Terminology

Plaid - An aggregator. An aggregator handles creating connections to financial institutions and retrieving information about those connections like bank accounts and transactions. Currently, Plaid is the only natively supported aggregator - contact Bloom support if you would like to use a different aggregator.
User - a user in Bloom Enablement Services represents a consumer. A user can have connections and tradelines.
Connection - a connection is used to pull tradeline data from an aggregator into Bloom Enablement Services.
Tradeline - a tradeline represents a user's account with recurring transactions.

Pre-requisites

Completed Bloom onboarding process.
Create a Plaid account. (To use a different aggregator, contact Bloom support.)

Getting Started

Obtain a Client ID and Client Secret for Authorization from the Bloom onboarding process. An organizationSlug is also needed, and obtained during onboarding.
Create a user via the RegisterOrganizationUser GraphQL Mutation, with the user's personal information and the organizationSlug obtained above. Optionally, check if a user exists with the email by using the UserExistsWithEmail GraphQL Query. In Bloom's sandbox environment, there is a limit of 100 users per organization. There is no limit in the production environment.
1. Grab the correct GraphQL URL from What URL Should I be Using . Use this URL for all following GraphQL operations.
2. Authentication is provided via 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
```
3. The user_id in the response needs to be stored against the consumer, and is required to interact with certain Enablement Services endpoints.
```
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
            }
        }
    }
}
```
Authenticate the user via 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's response. The session token will be in the response body, to be used for authorizing the user.
1. This token is valid for 2 hours. Upon expiration, regenerate one following the same process.
2. There may be a slight delay of no more than 10 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}}'

For the remaining steps, use the session token obtained in Step 3 for authentication unless otherwise stated. Provide the token as a bearer token in the headers. This is referred to as User Scoped Authentication (see Enablement Services Authentication). Replace session_token with the user's session token (no quotes).
```
Authorization: Bearer session_token
```

Check that the newly created user exists with the Me GraphQL query. Make sure you are using the User Scoped session token from the previous step for authentication.

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

Obtain a connection token from Plaid. See Plaid Processor Tokens.
All processor tokens created in Step 6 will be passed into the importConnections mutation in a single request. Use the ImportConnections Mutation to import the processor tokens.
1. This will return an array of connection objects, one for each imported token. This will start a workflow in the background to ingest the user's transactions into Bloom Enablement Services.
```
mutation ImportConnections {
    importConnections(input: {tokens: ["processor-sandbox-token-1", "processor-sandbox-token-2"]}) {
        connections {
            id
        }
    }
}
```
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 transaction ingestion is complete when the query shows the user's tradelines or once a user.synced webhook is received. A sample query is listed below, showing the first 5 tradelines for the user. In sandbox, this takes about 5 minutes.
1. Tradelines will be listed as eligible or ineligible via the isEligible property. Tradelines with isEligible == true and status == UNOPENED are able to be opened in the next step.
  1. Opening a tradeline begins the process of reporting it to credit bureaus.
2. 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
                    status
                    isEligible
                    paymentFrequency
                    createdAt
                    updatedAt
                    transactions(input: { first: 5 }) {
                        edges {
                            cursor
                            node {
                                id
                                date
                                value {
                                    amount
                                    currency
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Open a tradeline to be reported with one of the corresponding open tradeline methods. Each bill type has a corresponding mutation to open the tradeline (ie. rent, utility, telco).
1. You will need the tradeline_id obtained in the previous step as well as some extra details about the tradeline. Only tradelines with status == UNOPENED and isEligible == true can be opened.
2. After opening a tradeline the status will change to OPEN. Retrieve the status from the response to verify. This tradeline will now be furnished to the bureaus.
  For example, to open a Utility tradeline:

mutation OpenUtilityTradeline {
  openUtilityTradeline(
    id: "808b1fe0-8015-4df5-8bed-89d4acf68213"
    details: { isPrimaryAddress: true, utilityTypes: [WATER] }
  ) {
    tradeline {
      id
      status
      details {
        ... on UtilityTradelineDetails {
          isPrimaryAddress
          utilityTypes
        }
      }
    }
  }
}

Closing a Tradeline

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 Enablement Services Authentication. Following the example in Getting Started , the mutation may look like:

mutation CloseTradeline {
    closeTradeline(id: "808b1fe0-8015-4df5-8bed-89d4acf68213") {
        tradeline {
          id
          status
          details {
            ... on UtilityTradelineDetails {
              utilityTypes
              isPrimaryAddress
            }
          }
        }
    }
}

This will start a background workflow in the Bloom Enablement Services to ensure the tradeline will not be furnished.
After closing a tradeline the status will change to CLOSED. Retrieve the status from the response to verify.

Delete a User

To delete a user, use the DeleteMe mutation. Use the user's session token, mentioned in Enablement Services Authentication.

mutation DeleteMe {
  deleteMe {
    user {
      id
      name {
        first
        middle
        last
      }
    }
  }
}

What URL Should I Be Using

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

Sandbox vs Production

Currently, there is one main difference between the Sandbox and Production environments in Bloom's Enablement Services:

Sandbox: can import Plaid sandbox processor tokens
Production: can not import Plaid sandbox processor tokens (instead use production tokens)

Data is not shared between sandbox and production environments.

About

🐝TIP

Terminology

Pre-requisites

Getting Started

Closing a Tradeline

Delete a User

What URL Should I Be Using

Sandbox vs Production

🐝
TIP