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 covering 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.
Reference
- 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 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.
Prerequisites
- 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. Your organization's slug is also needed, obtained during this process as well.
- Create a user using the RegisterOrganizationUser GraphQL Mutation, with the user's information and the organization slug 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.
- Grab the correct GraphQL URL from What URL Should I be Using . Use this URL for all following GraphQL operations.
- Authorization 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 Authorization).
Authorization: Bearer client_id:client_secret - The user id in the response will be used in the next step, so hold on to it.
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 response's body will be the session token, to be used for authorizing the user.- This token is valid for 2 hours. When it expires, simply grab another one with this endpoint.
- There may be a slight delay of no more than 10 seconds between user creation, and when authentication can be performed.
- Use organization scoped authorization, 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 authorization unless otherwise stated. Provide the token as a bearer token in the headers. This is referred to as user scoped authorization (see Enablement Services Authorization). Replace
session_tokenwith 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 authorization.
query Me { me { id email phoneNumber status notificationPreferences createdAt updatedAt syncedAt closedAt name { first middle last } } } -
Obtain a connection token from Plaid.
- 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 in the background to ingest the user's transactions into 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 transaction 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.
- In sandbox, this takes about 5 minutes.
- Tradelines will be listed as eligible or ineligible via the
isEligibleproperty. Eligible tradelines can be imported in the next step. - 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 the tradeline has been successfully opened, use the Me query again. The imported tradeline should be listed with the
isOpenproperty set totrue. The tradeline is now ready to be furnished!
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 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 background 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 will be shown in the query result with the property
"isOpen": false, andisEligible: false.
Delete a User
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 - GraphQL:
https://api.bloomplus.dev/gql
- API:
- For production environments:
- API:
https://api.bloomplus.com - GraphQL:
https://api.bloomplus.com/gql
- API:
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 access tokens
- Production: can not import Plaid sandbox access tokens (instead use production tokens)
Data is not shared between sandbox and production environments.
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. When creating a sandbox user in plaid, we have had success with this config json.
- For a set of recurring payments to be eligible, the following requirements must be met:
- One payment within the last 90 days.
- At least 3 payments.
- For example: in the JSON provided below, the 'Rent payment' transaction group is eligible (at the time of writing). It has 3 payments, at least one of which occurred in the last 90 days.
- You may need to adjust the dates. One easy way adjust this payload is to prompt you favorite AI code editor with
give me this JSON data but shift all dates forward X months, where X is a more recent set of months.
- For a set of recurring payments to be eligible, the following requirements must be met:
{
"override_accounts": [
{
"type": "depository",
"subtype": "checking",
"transactions": [
{
"date_transacted": "2025-07-04",
"date_posted": "2025-07-04",
"amount": 1350,
"description": "Rent payment",
"currency": "USD"
},
{
"date_transacted": "2025-06-04",
"date_posted": "2025-06-04",
"amount": 1350,
"description": "Rent payment",
"currency": "USD"
},
{
"date_transacted": "2025-05-04",
"date_posted": "2025-05-04",
"amount": 1350,
"description": "Rent payment",
"currency": "USD"
},
{
"date_transacted": "2025-06-29",
"date_posted": "2025-06-29",
"amount": 248,
"description": "EVERGY MO WEST",
"currency": "USD"
},
{
"date_transacted": "2025-05-29",
"date_posted": "2025-05-29",
"amount": 221,
"description": "EVERGY MO WEST",
"currency": "USD"
},
{
"date_transacted": "2025-04-29",
"date_posted": "2025-04-29",
"amount": 212,
"description": "EVERGY MO WEST",
"currency": "USD"
},
{
"date_transacted": "2025-07-01",
"date_posted": "2025-07-01",
"amount": 115,
"description": "Verizon Wireless Bill Pay",
"currency": "USD"
},
{
"date_transacted": "2025-06-01",
"date_posted": "2025-06-01",
"amount": 115,
"description": "Verizon Wireless Bill Pay",
"currency": "USD"
},
{
"date_transacted": "2025-05-01",
"date_posted": "2025-05-01",
"amount": 115,
"description": "Verizon Wireless Bill Pay",
"currency": "USD"
},
{
"date_transacted": "2025-06-27",
"date_posted": "2025-06-27",
"amount": 17.99,
"description": "Netflix Subscription",
"currency": "USD"
},
{
"date_transacted": "2025-05-27",
"date_posted": "2025-05-27",
"amount": 17.99,
"description": "Netflix Subscription",
"currency": "USD"
},
{
"date_transacted": "2025-04-27",
"date_posted": "2025-04-27",
"amount": 17.99,
"description": "Netflix Subscription",
"currency": "USD"
},
{
"date_transacted": "2025-07-06",
"date_posted": "2025-07-06",
"amount": 120,
"description": "HelloFresh Subscription",
"currency": "USD"
},
{
"date_transacted": "2025-06-06",
"date_posted": "2025-06-06",
"amount": 120,
"description": "HelloFresh Subscription",
"currency": "USD"
},
{
"date_transacted": "2025-05-06",
"date_posted": "2025-05-06",
"amount": 120,
"description": "HelloFresh Subscription",
"currency": "USD"
},
{
"date_transacted": "2025-06-25",
"date_posted": "2025-06-25",
"amount": 25,
"description": "Water Company Water Bill",
"currency": "USD"
},
{
"date_transacted": "2025-05-25",
"date_posted": "2025-05-25",
"amount": 21,
"description": "Water Company Water Bill",
"currency": "USD"
},
{
"date_transacted": "2025-04-25",
"date_posted": "2025-04-25",
"amount": 23,
"description": "Water Company Water Bill",
"currency": "USD"
}
],
"identity": {
"names": [
"John Doe"
],
"phone_numbers": [
{
"primary": true,
"type": "home",
"data": "4673956022"
}
],
"emails": [
{
"primary": true,
"type": "primary",
"data": "[email protected]"
}
],
"addresses": [
{
"primary": true,
"data": {
"country": "US",
"city": "Malakoff",
"street": "2992 Cameron Road",
"postal_code": "14236",
"region": "NY"
}
}
]
}
}
]
}
- Obtain the Plaid client ID and secret from the Developers > Keys page.
- Get a Plaid Sandbox Token via the plaid API. Replace
plaid_client_idandplaid_client_secretwith your Plaid keys, andcustom_usernamewith your test user's username. Hang on the topublic_tokenreturned in the response. Make sure to include theidentityandtransactionsproducts as shown below. - The
institution_idcorresponds to a plaid sandbox institution. In this case, we wish to use a non-OAuth institution. See the Plaid documentation for more details. - Since this is sandbox only, we bypass the Plaid Link process .
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_109508",
"initial_products": ["identity", "transactions"],
"options": {
"override_username": "custom_username"
}
}'
- Exchange the Plaid sandbox token for an access token. Replace
plaid_client_idandplaid_client_secretwith your Plaid keys, andplaid_sandbox_tokenwith your Plaidpublic_token(the token returned in the previous step). Hold on to theaccess_tokenin the response. - According to the Plaid documentation , this token does not expire.
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 access token works, query the get accounts endpoint. This should correspond to the test data you provided when creating your test user in step 1. Replace
plaid_client_idandplaid_client_secretwith your Plaid keys, andplaid_access_tokenwith your Plaidaccess_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"
}'
-
If your integration requires a processor token (e.g., for use with Bloom Credit), you can create one by calling Plaid’s /processor/token/create endpoint.
This requires:-
The access_token from your Plaid Link flow
-
An account_id retrieved from the /accounts/get endpoint
Important:
The access_token must have been generated with these initial products
{ "initial_products": ["identity", "transactions"] }Without both products, the processor token may not return sufficient data for Bloom Credit services.
cURL Exmple:curl -X POST https://sandbox.plaid.com/processor/token/create \ -H "Content-Type: application/json" \ -d '{ "client_id": "{{plaid_client_id}}", "secret": "{{plaid_client_secret}}", "access_token": "{{plaid_access_token}}", "account_id": "{{plaid_account_id}}", "processor": "bloom_credit" }'Response:
{ "processor_token": "processor-sandbox-abc123...", "request_id": "abc123xyz" }Use this processor_token with the importConnection mutation to finalize the user's data import into Bloom.
-
Updated 1 day ago
What’s Next
Head to the API Reference