Correspondent API Overview

In financial services, a correspondent refers to an entity that provides services or represents customers in specified functions. For instance, a correspondent broker-dealer may process transactions, manage accounts, or perform other financial tasks on behalf of its customers.

As detailed here, the correspondent API allows you to retrieve details related to the correspondent you manage. Specifically, this API is designed to retrieve comprehensive information about your correspondent based on its unique identifier. Such information includes:

The correspondent's basic information.
Corporate contact details.
Support contact details.
Various permissions related to the services you're entitled to access.

POST/v1/correspondents

Create Correspondent

Create a new correspondent associated with a firm.

Request Body

Parameter	Description	Type	Input
`name`	Name of the correspondent	String	Required
`website`	Website of the correspondent	String	Required
`portfolioType`	Portfolio type of the correspondent. Possible values are `MARGIN` and `CASH`	String	Required
`address`	Address of the correspondent	Object	Required
`address.line1`	Address line 1	String	Required
`address.line2`	Address line 2	String	Optional
`address.city`	City	String	Required
`address.state`	State	String	Required
`address.postalCode`	Postal code	String	Required
`supportContact`	Support contact details	Object	Required
`supportContact.firstName`	First name of the support contact	String	Required
`supportContact.lastName`	Last name of the support contact	String	Required
`supportContact.email`	Email of the support contact	String	Required
`supportContact.phoneNumber`	Phone number of the support contact	String	Required
`corporateContact`	Corporate contact details	Object	Required
`corporateContact.firstName`	First name of the corporate contact	String	Required
`corporateContact.lastName`	Last name of the corporate contact	String	Required
`corporateContact.email`	Email of the corporate contact	String	Required
`corporateContact.phoneNumber`	Phone number of the corporate contact	String	Required
`permissions`	Permissions of the correspondent	Object	Required
`permissions.canCreateKeys`	Whether the correspondent can create keys	Boolean	Required
`permissions.sandboxAccess`	Whether the correspondent has sandbox access	Boolean	Required
`permissions.canRetrieveToken`	Whether the correspondent can retrieve token	Boolean	Required
`permissions.productionAccess`	Whether the correspondent has production access	Boolean	Required

Success Response

JSON

201 Created

{
    "status": "CREATED",
    "website": "https://www.uranusgroup.com",
    "portfolioType": "CASH",
    "permissions": {
    "canCreateKeys": true,
    "productionAccess": false,
    "canRetrieveToken": true,
    "sandboxAccess": true
},
    "address": {
    "line1": "66 Highland Rd",
    "city": "Fairview",
    "state": "MA",
    "postalCode": "40339",
    "line2": null
},
    "corporateContact": {
    "firstName": "John",
    "lastName": "Anderson",
    "phoneNumber": "+10027957886",
    "email": "r1FIWvxD@gmail.com",
    "middleName": null
},
    "supportContact": {
    "firstName": "Tom",
    "lastName": "Wilson",
    "phoneNumber": "+11991858279",
    "email": "cN118uhW@domain.com",
    "middleName": null
},
    "name": "Uranus Group LLC",
    "firmId": "7f7293e3-5a7c-44b2-a83d-188c7aea0ba7",
    "createdAt": "2024-04-14T03:31:30.867Z",
    "updatedAt": "2024-04-14T03:31:30.867Z",
    "correspondentId": "c1c741db-3188-4ef6-92aa-20ad928df739"
}

GET/v1/correspondents/all?page={page}&limit={limit}

Get All Correspondents

Fetch all correspondents associated with a firm.

Query Parameters

Parameter	Description	Type	Input
`page`	Page number, either 1 or greater. Default is 1. If more pages are available, the response will include a boolean flag `hasMore` set to `true`. If the page number is greater than the total number of pages, the response will be empty.	Integer	Required
`limit`	Number of items per page. Either 5, 10, 20, 50, or 100. Default is 50.	Integer	Required

Success Response

JSON

200 OK

{
  "correspondents": [
    {
      "createdAt": "2024-04-04T16:59:55.025Z",
      "updatedAt": "2024-04-04T16:59:55.025Z",
      "correspondentId": "24d8f65e-0850-48c8-a839-168780e2fcd1",
      "portfolioType": "MARGIN",
      "name": "Orion Finance LLC",
      "website": "https://www.orion.com",
      "status": "CREATED",
      "address": {
        "postalCode": "16244",
        "city": "Arlington",
        "line1": "434 Pine St",
        "line2": null,
        "state": "PA"
      },
      "supportContact": {
        "email": "53FWuRsY@hotmail.com",
        "phoneNumber": "+18917600351",
        "lastName": "Johnson",
        "firstName": "John",
        "middleName": null
      },
      "corporateContact": {
        "email": "qNwyXePr@yahoo.com",
        "phoneNumber": "+18298197798",
        "lastName": "Smith",
        "firstName": "Alex",
        "middleName": null
      },
      "permissions": {
        "canCreateKeys": false,
        "sandboxAccess": true,
        "canRetrieveToken": true,
        "productionAccess": true
      }
    }
  ],
    "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
}
}

GET/v1/correspondents/{correspondentId}

Get Correspondent

Use this endpoint to retrieve details of a specific correspondent.

Path Parameters

Parameter	Description	Type	Input
`correspondentId`	Unique ID for the correspondent	UUID	Required

Success Response

JSON

200 OK

{
  "createdAt": "2023-08-27T18:17:35.965Z",
  "updatedAt": "2023-08-27T18:17:35.965Z",
  "correspondentId": "4d811872-9304-48f9-9f4d-de589730c7af",
  "name": "Gravity Clearing LLC",
  "website": "https://gravity.markets",
  "portfolioType": "MARGIN",
  "status": "CREATED",
  "address": {
    "postalCode": "56278",
    "city": "Franklin",
    "line1": "848 Oak St",
    "line2": "123 Main street",
    "state": "NJ"
  },
  "supportContact": {
    "email": "NElXpoZ1@example.com",
    "phoneNumber": "+14724889409",
    "lastName": "Miller",
    "firstName": "Chris",
    "middleName": "James"
  },
  "corporateContact": {
    "email": "namemail@gmail.com",
    "phoneNumber": "+16872954664",
    "lastName": "Harris",
    "firstName": "Alex",
    "middleName": "Jack"
  },
  "permissions": {
    "canCreateKeys": true,
    "sandboxAccess": false,
    "canRetrieveToken": true,
    "productionAccess": false
  },
  "apiKeys": [
    {
      "createdAt": "2024-03-10T06:51:58.927Z",
      "updatedAt": "2024-03-10T06:51:58.927Z",
      "hashedKey": "fc78eadc5cbaa095f68bf60f46862c1cb94d1111c049e25f93366e191f5e1c5b",
      "label": "apiKeysName",
      "issuer": "CORRESPONDENT",
      "key": "4ec7...990e"
    }
  ]
}

PUT/v1/correspondents/{correspondentId}

Update Correspondent

Update an existing correspondent associated with a firm.

Path Parameters

Parameter	Description	Type	Input
`correspondentId`	Unique ID for the correspondent	UUID	Required

Request Body

Each field is optional. Only the fields that need to be updated should be included in the request body.

Parameter	Description	Type	Input
`name`	Name of the correspondent	String	Optional
`website`	Website of the correspondent	String	Optional
`portfolioType`	Portfolio type of the correspondent. Possible values are `MARGIN` and `CASH`	String	Optional
`address`	Address of the correspondent	Object	Optional
`address.line1`	Address line 1	String	Optional
`address.line2`	Address line 2	String	Optional
`address.city`	City	String	Optional
`address.state`	State	String	Optional
`address.postalCode`	Postal code	String	Optional
`supportContact`	Support contact details	Object	Optional
`supportContact.firstName`	First name of the support contact	String	Optional
`supportContact.lastName`	Last name of the support contact	String	Optional
`supportContact.email`	Email of the support contact	String	Optional
`supportContact.phoneNumber`	Phone number of the support contact	String	Optional
`corporateContact`	Corporate contact details	Object	Optional
`corporateContact.firstName`	First name of the corporate contact	String	Optional
`corporateContact.lastName`	Last name of the corporate contact	String	Optional
`corporateContact.email`	Email of the corporate contact	String	Optional
`corporateContact.phoneNumber`	Phone number of the corporate contact	String	Optional
`permissions`	Permissions of the correspondent	Object	Optional
`permissions.canCreateKeys`	Whether the correspondent can create keys	Boolean	Optional
`permissions.sandboxAccess`	Whether the correspondent has sandbox access	Boolean	Optional
`permissions.canRetrieveToken`	Whether the correspondent can retrieve token	Boolean	Optional
`permissions.productionAccess`	Whether the correspondent has production access	Boolean	Optional

Success Response

JSON

200 OK

{
    "createdAt": "2024-04-04T16:59:55.025Z",
    "updatedAt": "2024-04-14T03:51:56.574Z",
    "correspondentId": "24d8f65e-0850-48c8-a839-168780e2fcd1",
    "portfolioType": "MARGIN",
    "name": "Orion Finance LLC",
    "website": "https://www.orion.com",
    "status": "UPDATED",
    "address": {
        "line1": "434 Pine St",
        "line2": "#1300",
        "city": "Arlington",
        "state": "PA",
        "postalCode": "16244"
    },
    "supportContact": {
        "email": "53FWuRsY@hotmail.com",
        "phoneNumber": "+18917600351",
        "lastName": "Johnson",
        "firstName": "John",
        "middleName": null
    },
    "corporateContact": {
        "email": "qNwyXePr@yahoo.com",
        "phoneNumber": "+18298197798",
        "lastName": "Smith",
        "firstName": "Alex",
        "middleName": null
    },
    "permissions": {
        "canCreateKeys": false,
        "sandboxAccess": true,
        "canRetrieveToken": true,
        "productionAccess": true
    }
}