Get Customer

getCustomersCustomerId

get/customers/{customer_id}

Base URL: https://api.cert.tastyworks.com (Sandbox) · https://api.tastyworks.com (Production)

Returns the full customer resource, including name, addresses, suitability profile, and personal or entity details. For simplicity and security the customer's internal identifier is not exposed: pass `me` as the `customer_id` to fetch the customer linked to the current access token. Set `allow-missing=true` to avoid a 404 when the customer does not exist.

Code samples

curl -X GET 'https://api.cert.tastyworks.com/customers/me?allow-missing=true' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'User-Agent: tastytrade-docs-example/1.0'

import requests

url = "https://api.cert.tastyworks.com/customers/me?allow-missing=true"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "User-Agent": "tastytrade-docs-example/1.0",
}
resp = requests.get(url, headers=headers)
print(resp.status_code, resp.json())

const resp = await fetch("https://api.cert.tastyworks.com/customers/me?allow-missing=true", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "User-Agent": "tastytrade-docs-example/1.0",
  },
})
const data = await resp.json()
console.log(resp.status, data)

package main

import (
	"net/http"
	"io"
	"fmt"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cert.tastyworks.com/customers/me?allow-missing=true", nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("User-Agent", "tastytrade-docs-example/1.0")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.Status, string(out))
}

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.cert.tastyworks.com/customers/me?allow-missing=true"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("User-Agent", "tastytrade-docs-example/1.0")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.statusCode() + " " + resp.body());

Parameters

Name	In	Type	Description
customer_id*	path	string	Only a value of `me` is allowed. The API does not expose customers' internal identifiers. e.g. "me"
allow-missing	query	boolean	Does not raise a 404 if customer is missing e.g. true

Responses

200The full customer resource for the requested customer.application/json

Example response

{
  "data": {
    "id": "me",
    "first-name": "John",
    "first-surname": "string",
    "last-name": "Doe",
    "middle-name": "string",
    "prefix-name": "string",
    "second-surname": "string",
    "suffix-name": "string",
    "address": {
      "city": "string",
      "country": "string",
      "is-domestic": "string",
      "is-foreign": "string",
      "postal-code": "string",
      "state-region": "string",
      "street-one": "string",
      "street-three": "string",
      "street-two": "string"
    },
    "customer-suitability": {
      "id": "abc123",
      "annual-net-income": 0,
      "covered-options-trading-experience": "string",
      "customer-id": 1,
      "employer-name": "string",
      "employment-status": "string",
      "futures-trading-experience": "string",
      "job-title": "string",
      "liquid-net-worth": 1,
      "marital-status": "string",
      "net-worth": 0,
      "number-of-dependents": 0,
      "occupation": "string",
      "stock-trading-experience": "string",
      "tax-bracket": "string",
      "uncovered-options-trading-experience": "string"
    },
    "mailing-address": {
      "city": "string",
      "country": "string",
      "is-domestic": "string",
      "is-foreign": "string",
      "postal-code": "string",
      "state-region": "string",
      "street-one": "string",
      "street-three": "string",
      "street-two": "string"
    },
    "is-foreign": "string",
    "regulatory-domain": "string",
    "usa-citizenship-type": "Citizen",
    "home-phone-number": "string",
    "home-phone-number-details": "string",
    "mobile-phone-number": "+11231234567",
    "mobile-phone-number-details": "string",
    "work-phone-number": "string",
    "work-phone-number-details": "string",
    "birth-date": "2000-01-01",
    "email": "johndoe@nowhere.com",
    "external-id": "C0000037211",
    "foreign-tax-number": "string",
    "tax-number": "*****1234",
    "tax-number-type": "SSN",
    "birth-country": "string",
    "citizenship-country": "USA",
    "visa-expiration-date": "2024-01-15",
    "visa-type": "string",
    "agreed-to-margining": true,
    "subject-to-tax-withholding": true,
    "agreed-to-terms": true,
    "signature-of-agreement": true,
    "desk-customer-id": "abc123",
    "ext-crm-id": "abc123",
    "family-member-names": "string",
    "gender": "string",
    "has-industry-affiliation": true,
    "has-institutional-assets": "string",
    "has-listed-affiliation": true,
    "has-political-affiliation": true,
    "industry-affiliation-firm": "string",
    "is-investment-adviser": "string",
    "listed-affiliation-symbol": "AAPL",
    "political-organization": "string",
    "user-id": "abc123",
    "has-delayed-quotes": false,
    "has-pending-or-approved-application": "string",
    "is-professional": false,
    "permitted-account-types": "string",
    "created-at": "2024-01-15T14:30:00.000Z",
    "entity": {
      "id": "abc123",
      "address": {
        "city": "string",
        "country": "string",
        "is-domestic": "string",
        "is-foreign": "string",
        "postal-code": "string",
        "state-region": "string",
        "street-one": "string",
        "street-three": "string",
        "street-two": "string"
      },
      "business-nature": "string",
      "date-of-trust-creation": "string",
      "email": "string",
      "entity-officers": [
        {
          "id": "abc123",
          "external-id": "abc123",
          "first-name": "string",
          "last-name": "string",
          "middle-name": "string",
          "prefix-name": "string",
          "suffix-name": "string",
          "address": {
            "city": "string",
            "country": "string",
            "is-domestic": "string",
            "is-foreign": "string",
            "postal-code": "string",
            "state-region": "string",
            "street-one": "string",
            "street-three": "string",
            "street-two": "string"
          },
          "birth-country": "string",
          "birth-date": "2024-01-15",
          "citizenship-country": "string",
          "email": "string",
          "employer-name": "string",
          "employment-status": "string",
          "home-phone-number": "string",
          "is-foreign": "string",
          "job-title": "string",
          "marital-status": "string",
          "mobile-phone-number": "string",
          "number-of-dependents": "string",
          "occupation": "string",
          "owner-of-record": true,
          "relationship-to-entity": "string",
          "tax-number": "string",
          "tax-number-type": "string",
          "usa-citizenship-type": "string",
          "visa-expiration-date": "2024-01-15",
          "visa-type": "string",
          "work-phone-number": "string"
        }
      ],
      "entity-suitability": {
        "id": "abc123",
        "annual-net-income": 0,
        "covered-options-trading-experience": "string",
        "entity-id": 1,
        "futures-trading-experience": "string",
        "liquid-net-worth": 1,
        "net-worth": 0,
        "stock-trading-experience": "string",
        "tax-bracket": "string",
        "uncovered-options-trading-experience": "string"
      },
      "entity-type": "string",
      "foreign-institution": "string",
      "grantor-birth-date": "2024-01-15",
      "grantor-email": "string",
      "grantor-first-name": "string",
      "grantor-last-name": "string",
      "grantor-middle-name": "string",
      "grantor-tax-number": "string",
      "has-foreign-bank-affiliation": "string",
      "has-foreign-institution-affiliation": "string",
      "is-domestic": "string",
      "legal-name": "string",
      "mailing-address": {
        "city": "string",
        "country": "string",
        "is-domestic": "string",
        "is-foreign": "string",
        "postal-code": "string",
        "state-region": "string",
        "street-one": "string",
        "street-three": "string",
        "street-two": "string"
      },
      "phone-number": "string",
      "secretary-name": "string",
      "tax-election": "string",
      "tax-number": "string"
    },
    "identifiable-type": "Person",
    "person": {
      "external-id": "abc123",
      "first-name": "string",
      "last-name": "string",
      "middle-name": "string",
      "prefix-name": "string",
      "suffix-name": "string",
      "birth-country": "string",
      "birth-date": "2024-01-15",
      "citizenship-country": "string",
      "usa-citizenship-type": "string",
      "visa-expiration-date": "2024-01-15",
      "visa-type": "string",
      "employer-name": "string",
      "employment-status": "string",
      "job-title": "string",
      "marital-status": "string",
      "number-of-dependents": "string",
      "occupation": "string"
    }
  },
  "context": "/customers/{customer_id}"
}

Schema

datarequiredobject (Customer)
A tastytrade customer, including name, residential and mailing addresses, suitability profile, and either personal or entity details. Fetched via GET /customers/{customer_id} using `me` as the identifier.
- idstring
  Customer identifier. The API returns `me` rather than the internal id.
  example: "me"
- first-namestring
  Customer's first name.
  example: "John"
- first-surnamestring
- last-namestring
  Customer's last name.
  example: "Doe"
- middle-namestring
- prefix-namestring
- second-surnamestring
- suffix-namestring
- addressobject{9 fields}
- customer-suitabilityobject{16 fields}
- mailing-addressobject{9 fields}
- is-foreignstring
  Whether the customer is classified as foreign. Note: the wire value is a JSON boolean (e.g. false), although this schema declares a string.
- regulatory-domainstring
- usa-citizenship-typestring
  U.S. citizenship classification, for example Citizen.
  example: "Citizen"
- home-phone-numberstring
- home-phone-number-detailsstring
- mobile-phone-numberstring
  Customer's mobile phone number, e.g. +11231234567.
  example: "+11231234567"
- mobile-phone-number-detailsstring
- work-phone-numberstring
- work-phone-number-detailsstring
- birth-datestring
  Customer's date of birth (YYYY-MM-DD).
  example: "2000-01-01"
- emailstring
  Customer's email address.
  example: "johndoe@nowhere.com"
- external-idstring
  External customer identifier used by tastytrade's backoffice systems.
  example: "C0000037211"
- foreign-tax-numberstring
- tax-numberstring
  Masked tax identification number on file.
  example: "*****1234"
- tax-number-typestring
  Type of tax identification number on file, for example SSN.
  example: "SSN"
- birth-countrystring
- citizenship-countrystring
  Country of citizenship.
  example: "USA"
- visa-expiration-datestring
- visa-typestring
- agreed-to-marginingboolean
  Whether the customer has agreed to margining.
  example: true
- subject-to-tax-withholdingboolean
- agreed-to-termsboolean
  Whether the customer has agreed to the account terms.
  example: true
- signature-of-agreementboolean
- desk-customer-idstring
- ext-crm-idstring
- family-member-namesstring
- genderstring
- has-industry-affiliationboolean
- has-institutional-assetsstring
- has-listed-affiliationboolean
- has-political-affiliationboolean
- industry-affiliation-firmstring
- is-investment-adviserstring
- listed-affiliation-symbolstring
- political-organizationstring
- user-idstring
- has-delayed-quotesboolean
  Whether the customer receives delayed market data quotes.
  example: false
- has-pending-or-approved-applicationstring
- is-professionalboolean
  Whether the customer is classified as a professional for market-data purposes.
  example: false
- permitted-account-typesstring
- created-atstring <date-time>
- entityobject{24 fields}
- identifiable-typestring
  Whether the customer is identified as a Person or an Entity.
  example: "Person"
- personobject{18 fields}
contextrequiredstring
example: "/customers/{customer_id}"

401Missing or expired access token, or a missing/malformed User-Agent header. Send a valid Authorization: Bearer token and a User-Agent like my-app/1.0.application/json

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "No valid access token was provided; access tokens expire after 15 minutes."
  }
}

Schema

errorrequiredobject
- coderequiredstring
  Machine-readable error code (see the Error reference).
- messagerequiredstring
  Human-readable explanation.
- errorsarray<object>{3 fields}
  Present for multi-error / validation failures; one entry per problem.

404No customer matches the supplied customer_id. Pass `me` to resolve the current customer, or set allow-missing=true to suppress this error.application/json

Example response

{
  "error": {
    "code": "string",
    "message": "string",
    "errors": [
      {
        "code": "string",
        "message": "string",
        "domain": "string"
      }
    ]
  }
}

Schema

errorrequiredobject
- coderequiredstring
  Machine-readable error code (see the Error reference).
- messagerequiredstring
  Human-readable explanation.
- errorsarray<object>{3 fields}
  Present for multi-error / validation failures; one entry per problem.

429Request rate exceeded. Back off exponentially and reduce request rate.application/json

Example response

{
  "error": {
    "code": "string",
    "message": "string",
    "errors": [
      {
        "code": "string",
        "message": "string",
        "domain": "string"
      }
    ]
  }
}

Schema

errorrequiredobject
- coderequiredstring
  Machine-readable error code (see the Error reference).
- messagerequiredstring
  Human-readable explanation.
- errorsarray<object>{3 fields}
  Present for multi-error / validation failures; one entry per problem.

Rate-limit class: read · idempotent — Rate limits & backoff
Error reference — codes, causes, and fixes

Agents: this page is also Markdown (with the embedded OpenAPI definition) — append .md or send Accept: text/markdown. Index at /llms.txt.

Get Customer

Code samples

Parameters

Responses

Related