NAV
curl

← Home

Counterparties

Introduction

Disclaimer: This documentation is currently in Alpha and is subject to drastic change.

This is the official reference documentation for the SVB Counterparties API. Please see the authentication documentation for access information.

The Counterparties API follows the same conventions as SVB’s other APIs. Please see the documentation on API conventions for more information.


Background

The Counterparty object represents an entity on the other side of a transaction; this can be a person, business, government, or bank. For example, if you send a wire transfer to a vendor, that vendor is the counterparty for the wire.

Counterparties can be used to simplify an app and make it more secure. The recommended best practice is to store the Counterparty ID and use this ID in API calls instead of storing account credentials.

Counterparties

Attributes

Example Counterparty object:

{
  "id": "123",
  "account_number": "123456789",
  "address_line1": "123 Parrot Street",
  "address_line2": "Apt. 311",
  "city": "San Francisco",
  "state": "CA",
  "country": "US",
  "postal_code": "94105",
  "description": "Important vendor",
  "email_address": "counterparty@svb.com",
  "name": "Counterparty Co.",
  "metadata": {"foo": "bar"},
  "routing_number": "121140399",
  "type": "counterparty",
  "wire_routing_Number": "121145145",
  "url": "/v1/counterparties/123"
}
Name Type Description
id string Uniquely identifies each counterparty object.
account_number string The account number.
account_type enum(checking, savings) The type of account.
address_line1 string Mailing address street.
address_line2 string Mailing address apartment, suite, building, etc.
city string Mailing address city.
state string Mailing address state (if applicable).
country string Mailing address country (ISO 3166-1 alpha-2).
postal_code string Mailing address postal_code.
description string A description of the counterparty.
email_address string The counterparty’s email address.
metadata object Optional metadata to associate with the counterparty.
name string The counterparty’s name.
routing_number string The 9-digit ABA routing number.
wire_routing_number string An alternative routing number if required by the bank.

Create a Counterparty

Example request:

curl "https://api.svb.com/v1/counterparties" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
        "data": {
          "account_number": "123456777",
          "account_type": "checking",
          "address_line1": "789 Party Street",
          "city": "San Francisco",
          "state": "CA",
          "country": "US",
          "postal_code": "94105",
          "description": "Important vendor",
          "email_address": "staff@counterparty.co",
          "name": "Counterparty Co.",
          "routing_number": "121140399"
        }
      }'

Example response:

{
  "data": {
    "id": "123",
    "account_number": "123456777",
    "address_line1": "789 Party Street",
    "address_line2": null,
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105",
    "description": "Important vendor",
    "email_address": "staff@counterparty.co",
    "name": "Counterparty Co.",
    "metadata": null,
    "routing_number": "121140399",
    "type": "counterparty",
    "wire_routing_number": null,
    "url": "/v1/counterparties/123"
  }
}

Request:

POST /v1/counterparties

Parameters:

Name Type Required? Description
account_number string R The counterparty’s account number.
account_type enum(checking, savings) R The type of account.
address_line1 string Mailing address street.
address_line2 string Mailing address apartment, suite, etc.
city string Mailing address city.
state string Mailing address state (if applicable).
country string Mailing address country (ISO 3166-1 alpha-2).
postal_code string Mailing address postal_code.
description string A description of the counterparty.
email_address string The counterparty’s email address.
metadata object Optional metadata to associate with the counterparty.
name string R The counterparty’s name.
routing_number string R The 9-digit ABA routing number.
wire_routing_number string An alternative routing number if required by the bank.

Response:

200 OK The new counterparty resource.

Retrieve a Counterparty

Example request:

curl "https://api.svb.com/v1/counterparties/123" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": {
    "id": "123",
    "account_number": "123456789",
    "address_line1": "123 Parrot Street",
    "address_line2": "Apt. 311",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105",
    "description": "Important vendor",
    "email_address": "counterparty@svb.com",
    "name": "Counterparty Co.",
    "metadata": {"foo": "bar"},
    "routing_number": "121140399",
    "type": "counterparty",
    "wire_routing_Number": "121145145",
    "url": "/v1/counterparties/123"
  }
}

Request:

GET /v1/counterparties/:id

Response:

200 OK The counterparty resource.

Update a Counterparty

Example request:

curl "https://api.svb.com/v1/counterparties/123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -X PATCH \
    -d '{
          "data": {
            "name": "Partycounter Co."
          }
        }'

Example response:

{
  "data": {
    "id": "123",
    "account_number": "123456789",
    "address_line1": "123 Parrot Street",
    "address_line2": "Apt. 311",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105",
    "description": "Important vendor",
    "email_address": "counterparty@svb.com",
    "name": "Partycounter Co.",
    "metadata": {"foo": "bar"},
    "routing_number": "121140399",
    "type": "counterparty",
    "wire_routing_Number": "121145145",
    "url": "/v1/counterparties/123"
  }
}

Request:

PATCH /v1/counterparties/:id

Parameters:

Name Type Required? Description
address_line1 string Mailing address street.
address_line2 string Mailing address apartment number, suite, etc.
city string Mailing address city.
state string Mailing address state (if applicable).
country string Mailing address country (ISO 3166-1 alpha-2).
postal_code string Mailing address postal_code.
description string A description of the counterparty.
email_address string The counterparty’s email address.
metadata object Optional metadata to associate with the counterparty.
name string The counterparty’s name.
wire_routing_number string An alternative routing number if required by the bank.

Response:

200 OK The updated counterparty resource.

List all Counterparties

Example request:

curl "https://api.svb.com/v1/counterparties" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    {
      "id": 123,
      "type": "counterparty",
      "url": "/v1/counterparties/123"
    },
    {
      "id": 122,
      "type": "counterparty",
      "url": "/v1/counterparties/122"
    },
    {
      "id": 121,
      "type": "counterparty",
      "url": "/v1/counterparties/121"
    }
  ],
  "links": {
    "first": "/v1/counterparties",
    "next": null
  }
}

Request:

GET /v1/counterparties

Response:

200 OK List of counterparty resources.