Correlation ID - Value in Knowing

When you think of Dwolla, you might just think of bank transfers. While this is our specialty, we offer additional features and functionality on our platform that can help make your life, as a developer, easier.

The need to correlate transfers after creation was a request we kept hearing about from our Clients. To make things easier on our Clients, we created an optional field called a correlationId.

Value in Knowing

You can use this unique identifier to bind messages when creating Customer or Transfer resources. Let’s take a look at what the Correlation ID textbook definition is:

A unique string value attached to a customer which can be used for traceability between Dwolla and your application. Must be less than 255 characters and contain no spaces. Acceptable characters are: a-Z, 0-9, -, ., and _. Note: Sensitive Personal Identifying Information (PII) should not be used in this field and it is recommended to use a random value for correlationId, like a UUID. Uniqueness is enforced on correlationId across Customers.

The Correlation ID provides a useful way to ensure your application database is in sync with actions done with the Dwolla API.

To illustrate this, let’s say your application is about to initiate a transfer. You have your own internal identifier assigned to transfers on your end. The problem is that you will not know the Dwolla Transfer Id until the transfer has been completed. For our API clients creating multiple transfers per second, finding ways to correspond Dwolla transfer resources with your internal Ids can quickly become cumbersome. The Correlation ID can help eliminate the need to guess how to correlate resources after creation.

The Correlation ID helps improve the traceability of a transaction, between two systems; it allows you to create an ID and use that ID from the point of origin on, instead of waiting for a response from Dwolla to then get an ID.

Transfer Example

Create a Transfer

On transfer creation, you can assign a Correlation ID to a request by adding it in the request body.

POST api-sandbox.dwolla.com/transfers HTTP/1.1
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0KrTcopas1SyxGrW7eG72vcjUdmxF9P4Jfwl4TSggnciEjA1Sg
Content-Type: application/json
Idempotency-Key: cd5d7e84-6d52-4960-ae15-d1d62b3b1e6d

{
   "_links": {
       "source": {
           "href": "https://api-sandbox.dwolla.com/funding-sources/3152c22b-3d72-442d-a83b-e575df3a043e"
       },
       "destination": {
           "href": "https://api-sandbox.dwolla.com/funding-sources/456ef23f-d51c-4781-8fb6-dd0cb8a40192"
       
   },
   "amount": {
       "currency": "USD",
       "value": "10.00"
   },
   "correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}
. . .

HTTP/1.1 201 Created
Location →https://api-sandbox.dwolla.com/transfers/6c9cf99f-a987-e911-8119-d7bc0de34d9c

Retrieve the Transfer

You can then find the Correlation ID by retrieving the transfer via the API.

GET api-sandbox.dwolla.com/transfers/6c9cf99f-a987-e911-8119-d7bc0de34d9c HTTP/1.1
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0KrTcopas1SyxGrW7eG72vcjUdmxF9P4Jfwl4TSggnciEjA1Sg

{
    "_links": {
        "cancel": {
            "href": "https://api-sandbox.dwolla.com/transfers/6c9cf99f-a987-e911-8119-d7bc0de34d9c",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "source": {
            "href": "https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "funding-transfer": {
            "href": "https://api-sandbox.dwolla.com/transfers/6b9cf99f-a987-e911-8119-d7bc0de34d9c",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "destination-funding-source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/456ef23f-d51c-4781-8fb6-dd0cb8a40192",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/transfers/6c9cf99f-a987-e911-8119-d7bc0de34d9c",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "source-funding-source": {
            "href": "https://api-sandbox.dwolla.com/funding-sources/3152c22b-3d72-442d-a83b-e575df3a043e",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "destination": {
            "href": "https://api-sandbox.dwolla.com/accounts/30a6cb55-1754-4948-b431-ebe48288ef25",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "account"
        
    },
    "id": "6c9cf99f-a987-e911-8119-d7bc0de34d9c",
    "status": "pending",
    "amount": {
        "value": "10.00",
        "currency": "USD"
    },
    "created": "2019-06-05T15:50:22.447Z",
    "clearing": {
        "source": "next-day"
    },
    "correlationId": "8a2cdc8d-629d-4a24-98ac-40b735229fe2"
}

Customers Example

Create a Customer

On Customer creation, you can assign a Correlation ID to a request by adding it in the request body.

POST api-sandbox.dwolla.com/customers
Accept: application/vnd.dwolla.v1.hal+json
Content-Type: application/json
Authorization: Bearer 0KrTcopas1SyxGrW7eG72vcjUdmxF9P4Jfwl4TSggnciEjA1Sg
Idempotency-Key: cd5d7e84-6d52-4960-ae15-d1d62b3b1e6d
{
    "firstName": "Cory",
    "lastName": "Anderson",
    "email": "CorysCoolEmail@emailProvider.com",
    "ipAddress": "143.156.7.8",
    "correlationId": "InternalId90D938E2-43C7-494D-8B51-8F69B37410EB"
}
. . .

HTTP/1.1 201 Created
Location →https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32

Retrieve the Customer

You can then find the Correlation ID by retrieving the Customer via the API.

GET api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32 HTTP/1.1
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0KrTcopas1SyxGrW7eG72vcjUdmxF9P4Jfwl4TSggnciEjA1Sg

{
    "_links": {
        "deactivate": {
            "href": "https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "edit-form": {
            "href": "https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32",
            "type": "application/vnd.dwolla.v1.hal+json; profile=\"https://github.com/dwolla/hal-forms\"",
            "resource-type": "customer"
        },
        "edit": {
            "href": "https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "customer"
        },
        "funding-sources": {
            "href": "https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32/funding-sources",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "funding-source"
        },
        "transfers": {
            "href": "https://api-sandbox.dwolla.com/customers/f2b2256e-61aa-432a-aaa4-5314652a4f32/transfers",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        
    },
    "id": "f2b2256e-61aa-432a-aaa4-5314652a4f32",
    "firstName": "Cory",
    "lastName": "Anderson",
    "email": "CorysCoolEmail@emailProvider.com",
    "type": "unverified",
    "status": "unverified",
    "created": "2019-06-05T16:07:38.833Z",
    "correlationId": "InternalId90D938E2-43C7-494D-8B51-8F69B37410EB"
}

Wrapping it Up

As a basic premise, the Correlation ID is simple. It’s a value that is common to all requests and responses in a given Dwolla Transfer or Customer resource creation. Whether you use this optional parameter to correlate internal transferIds, order confirmation numbers, businessIds, or even a timestamp, with this simplicity you get a lot of power.

The nature of the Dwolla API means that correlating Dwolla resources to your own system can be difficult to track. Having a common “tag” among elements in a created resource allows a common reference which can also be handy in logging and auditing, ultimately allowing you to spend your time fixing the problem rather than finding the problem.

For instance, you can use the API to find a transfer.

GET api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4/transfers?correlationId=invoicenumber_27471 HTTP/1.1
Accept: application/vnd.dwolla.v1.hal+json
Authorization: Bearer 0KrTcopas6SyxGrW7eG72vcjUdmxF9P4Jfwl4TSggnciEjA1Sg
{
    "_links": {
        "self": {
            "href": "https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4/transfers?correlationId=invoicenumber_27471",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "first": {
            "href": "https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4/transfers?correlationId=invoicenumber_27471&limit=25&offset=0",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        },
        "last": {
            "href": "https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4/transfers?correlationId=invoicenumber_27471&limit=25&offset=0",
            "type": "application/vnd.dwolla.v1.hal+json",
            "resource-type": "transfer"
        
    },
    "_embedded": {
        "transfers": [
            
                "_links": {
                    "cancel": {
                        "href": "https://api-sandbox.dwolla.com/transfers/2dc087a9-4091-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    },
                    "source": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/3152c22b-3d72-442d-a83b-e575df3a043e",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "funding-source"
                    },
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/transfers/2dc087a9-4091-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    },
                    "funded-transfer": {
                        "href": "https://api-sandbox.dwolla.com/transfers/2ec087a9-4091-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    },
                    "destination": {
                        "href": "https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "customer"
                    
                },
                "id": "2dc087a9-4091-e911-811a-9de799d3b148",
                "status": "pending",
                "amount": {
                    "value": "2470.00",
                    "currency": "USD"
                },
                "created": "2019-06-17T20:44:21.350Z",
                "clearing": {
                    "source": "next-day"
                },
                "correlationId": "invoicenumber_27471",
                "individualAchId": "IDA7ZNXK"
            },
            
                "_links": {
                    "cancel": {
                        "href": "https://api-sandbox.dwolla.com/transfers/2ec087a9-4091-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    },
                    "source": {
                        "href": "https://api-sandbox.dwolla.com/customers/c2bdcc87-91cd-41dd-9b06-5e31d4d3bbe4",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "customer"
                    },
                    "funding-transfer": {
                        "href": "https://api-sandbox.dwolla.com/transfers/2dc087a9-4091-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    },
                    "destination-funding-source": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/1b9c365c-940c-41b3-81d0-f8c3ec973df4",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "funding-source"
                    },
                    "self": {
                        "href": "https://api-sandbox.dwolla.com/transfers/2ec087a9-4091-e911-811a-9de799d3b148",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "transfer"
                    },
                    "source-funding-source": {
                        "href": "https://api-sandbox.dwolla.com/funding-sources/3152c22b-3d72-442d-a83b-e575df3a043e",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "funding-source"
                    },
                    "destination": {
                        "href": "https://api-sandbox.dwolla.com/accounts/30a6cb55-1754-4948-b431-ebe48288ef25",
                        "type": "application/vnd.dwolla.v1.hal+json",
                        "resource-type": "account"
                    
                },
                "id": "2ec087a9-4091-e911-811a-9de799d3b148",
                "status": "pending",
                "amount": {
                    "value": "2470.00",
                    "currency": "USD"
                },
                "created": "2019-06-17T20:44:21.333Z",
                "clearing": {
                    "source": "next-day"
                },
                "correlationId": "invoicenumber_27471"  
    },
    "total": 2
}

Got a question about Correlation ID and its application? Let’s talk! Be sure to comment below.

1 Like