# Correlation ID - Value in Knowing

**URL:** <https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238>\
**Category:** Feature-Highlights\
**Created:** [June 24, 2019, 4:57pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238 "2019-06-24T16:57:00Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![CoolStoryCory](https://sea2.discourse-cdn.com/dwolla/user_avatar/discuss.dwolla.com/coolstorycory/32/2160_2.png) [@CoolStoryCory](https://discuss.dwolla.com/u/CoolStoryCory)\
**Post date:** [June 24, 2019, 4:57pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/1 "2019-06-24T16:57:00Z")

</div>

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](https://www.dwolla.com/updates/dwolla-partner-feedback-and-correlationid/).

> 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.

```auto
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.

```auto
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.

```auto
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.

```auto
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.

```auto
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.

---

<div class="post-metadata">

**Author:** ![jlansden](https://avatars.discourse-cdn.com/v4/letter/j/258eb7/32.png) [@jlansden](https://discuss.dwolla.com/u/jlansden)\
**Post date:** [December 22, 2020, 9:10pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/2 "2020-12-22T21:10:09Z")

</div>

Hi, can a correlationID be modified or updated after the fact? Thanks

---

<div class="post-metadata">

**Author:** ![kmoreira](https://sea2.discourse-cdn.com/dwolla/user_avatar/discuss.dwolla.com/kmoreira/32/2718_2.png) [@kmoreira](https://discuss.dwolla.com/u/kmoreira)\
**Post date:** [December 23, 2020, 3:07pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/3 "2020-12-23T15:07:39Z")

</div>

Hi @jlansden!

The correlationID cannot be modified at this time. However, could you provide your idea of a good use case for this? I’d be happy to create a ticket for it on our end. 🙂

---

<div class="post-metadata">

**Author:** ![jlansden](https://avatars.discourse-cdn.com/v4/letter/j/258eb7/32.png) [@jlansden](https://discuss.dwolla.com/u/jlansden)\
**Post date:** [December 23, 2020, 4:04pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/4 "2020-12-23T16:04:54Z")

</div>

We have been building iteratively so in some old cases we don’t have a correlation ID or we have the wrong one due to a bug. I think I saw a comment from another user with the same problem.

---

<div class="post-metadata">

**Author:** ![kmoreira](https://sea2.discourse-cdn.com/dwolla/user_avatar/discuss.dwolla.com/kmoreira/32/2718_2.png) [@kmoreira](https://discuss.dwolla.com/u/kmoreira)\
**Post date:** [December 23, 2020, 4:06pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/5 "2020-12-23T16:06:22Z")

</div>

Thank you, @jlansden! This is valuable. I will add this reasoning to the ticket.

---

<div class="post-metadata">

**Author:** ![klue](https://sea2.discourse-cdn.com/dwolla/user_avatar/discuss.dwolla.com/klue/32/1917_2.png) [@klue](https://discuss.dwolla.com/u/klue)\
**Post date:** [October 3, 2021, 6:43pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/6 "2021-10-03T18:43:06Z")

</div>

Hey @kmoreira,

Could you clarify a few things for me?

1. The Correlation ID must be **less than** 255 characters? Not **less than or equal to** 255?
2. Do you enforce a minimum number of characters?
3. Can the first/last character match any of the acceptable values? Are the following okay?  
•.a09-4590.b3yDD5N  
• -a09-4590.b3yDD5N  
• \_a09-4590.b3yDD5N

---

<div class="post-metadata">

**Author:** ![kmoreira](https://sea2.discourse-cdn.com/dwolla/user_avatar/discuss.dwolla.com/kmoreira/32/2718_2.png) [@kmoreira](https://discuss.dwolla.com/u/kmoreira)\
**Post date:** [October 4, 2021, 12:27pm UTC](https://discuss.dwolla.com/t/correlation-id-value-in-knowing/5238/7 "2021-10-04T12:27:06Z")

</div>

Hi @klue

I just created some of the scenarios from your questions using our [Postman Collection](https://app.getpostman.com/run-collection/e946a89ed19313cce582). Below are the answers:

> [@klue](#):
>
> The Correlation ID must be **less than** 255 characters? Not **less than or equal to** 255?

Up to 255, so less than or equal to 255.

> [@klue](#):
>
> Do you enforce a minimum number of characters?

Yes. It must have at least one value

> [@klue](#):
>
> Can the first/last character match any of the acceptable values? Are the following okay?  
> •.a09-4590.b3yDD5N  
> • -a09-4590.b3yDD5N  
> • \_a09-4590.b3yDD5N

The above would not be okay because correlationIds must be a string. However, if they are in string format, this will be acceptable.

Our [docs](https://docs.dwolla.com/) have more information on correlation ids as well as code samples.