Introduction

You can incorporate your existing user model into Pinwheel to simplify your integration and improve coverage. Start by providing us with your own internal user identifier when you initiate an account connection. Providing your internal user identifier is useful because:

• Any account data you receive from us includes the user ID you provide, making it easier to associate that data with your own internal user model.
• Pinwheel can determine if a user makes repeated connection attempts, such as across different platforms. We use this information to improve conversion.
• Simple Direct Deposit only integrations don't need to track any Pinwheel identifiers, except for troubleshooting purposes.

Implementation

Step 1: Create a Link Token with your user ID

Provide your user ID via the end_user_id parameter in POST /v1/link_tokens. Pinwheel will accept any UTF-8 string from 1 and 255 characters in length. We will remove whitespace at the start and end of the identifier.

Do not provide any personally identifiable information ("PII" such as social security numbers, first/last name, bank account numbers, etc.) in this field since this identifier is logged.

Pinwheel associates accounts and data with the value you provide in end_user_id. You can specify the same end_user_id across multiple Link Tokens to affiliate multiple accounts with a single user.

Here's what an example request to POST /v1/link_tokens with end_user_id might look like:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "required_jobs": ["employment", "income", "paystubs"],
  "end_user_id": "my_user_12345"
}

Step 2: Your user connects their account

Your user logs in via Link and connects to their account. See our Implementation Guide for more information.

Step 3: Consume end user data

Pinwheel provides two ways to make end user data available to you:

Webhooks

By registering a webhook, you can receive account data automatically when your user connects their account.

If you've specified an end_user_id, then all webhook events will contain a reference to your supplied user identifier.

For example, the account.added webhook event would include the end_user_id from Step 1:

{
  "event": "account.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "end_user_id": "my_user_12345",
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "link_token_id": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "platform_name": "Justworks",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true,
    "monitoring_status": "active"
  }
}

API

If you've specified end_user_id during Link Token creation, you can access a list of that end user's accounts via GET /v1/end_users/{end_user_id}/accounts. This endpoint returns a paginated list of the accounts associated with the end user:

{
    "data": [
        {
            "id": "eb240ec6-a227-47ca-b7c7-fbbdfe7170a0",
            "created_at": "2021-01-06T15:59:13.530178+00:00",
            "link_token_id": "bd2c09e7-1303-46d5-87c0-0ffa572d7ae4", 
            "platform_id": "fce3eee0-285b-496f-9b36-30e976194736", 
            "connected": true, 
            "monitoring_status": "active", 
            "data_updated_at": {
                "direct_deposit_allocations": "2021-01-08T00:00:00.000000+00:00"
            },
            "data_refreshed_at": {
                "direct_deposit_allocations": "2021-01-09T00:00:00.000000+00:00"
            },
            "end_user_id": "my_user_12345"
        },
    ],
    "meta": {
        "count": 1,
        "next_cursor": null
    }
}

Please contact [email protected] for access to our Dashboard.