Customers

The Customer object stores information about the businesses and individuals associated with your Application.

Customers are created in three ways:

  • Automatically via Sphere, when a user pays for one of your products via paymentLink.
  • Automatically via Sphere, when users go through your sphere ramp instance.
  • Manually by you, the developer via API.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the contact.

  • Name
    username
    Type
    string
    Description

    The username for the contact.

  • Name
    phone_number
    Type
    string
    Description

    The phone number for the contact.

  • Name
    avatar_url
    Type
    string
    Description

    The avatar image URL for the contact.

  • Name
    display_name
    Type
    string
    Description

    The contact display name in the contact list. By default, this is just the username.

  • Name
    conversation_id
    Type
    string
    Description

    Unique identifier for the conversation associated with the contact.

  • Name
    last_active_at
    Type
    timestamp
    Description

    Timestamp of when the contact was last active on the platform.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the contact was created.

Customer Object

    
  {
      "id": "customer_fgsandjkgdsnbagjksadngj",
      "type": "individual",
      "kycStatus": "approved",
      "tosStatus": "approved",
      "kycRequirements": [],
      "website": null,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@gmail.com",
      "phoneNumber": "+1234567890",
      "meta": {},
      "address": {
          "street": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94107",
          "country": "US"
      },
      "wallets": [
          "wallet_fgsandjkgdsnbagjksadngj",
          "wallet_fgsandjkgdsnbagjksadngj",
          "wallet_fgsandjkgdsnbagjksadngj"
      ],
      "bankAccounts": [
          "bank_account_fgsandjkgdsnbagjksadngj",
          "bank_account_fgsandjkgdsnbagjksadngj",
          "bank_account_fgsandjkgdsnbagjksadngj"
      ],
      "ubos": [
          {
              "id": "ubo_fgsandjkgdsnbagjksadngj",
              "firstName": "Jane",
              "lastName": "Doe",
              "email": "",
              "phoneNumber": "",
              "address": {
                  "street": "123 Main St",
                  "city": "San Francisco",
                  "state": "CA",
                  "postalCode": "94107",
                  "country": "US"
              },
              "created": "2019-01-01T00:00:00Z",
              "updated": "2019-01-01T00:00:00Z",
              "kycRequirements": []
          },
          {
              "id": "ubo_fgsandjkgdsnbagjksadngj",
              "firstName": "Jane",
              "lastName": "Doe",
              "email": "",
              "phoneNumber": "",
              "address": {
                  "street": "123 Main St",
                  "city": "San Francisco",
                  "state": "CA",
                  "postalCode": "94107",
                  "country": "US"
              },
              "created": "2019-01-01T00:00:00Z",
              "updated": "2019-01-01T00:00:00Z",
              "kycRequirements": []
          }
      ],
      "mock": false,
      "created": "2019-01-01T00:00:00Z",
      "updated": "2019-01-01T00:00:00Z"
  }
POST/v1/customer

Create a customer

This endpoint allows you to add a new contact to your contact list in Protocol. To add a contact, you must provide their Protocol username and phone number.

Required attributes

  • Name
    username
    Type
    string
    Description

    The username for the contact.

  • Name
    phone_number
    Type
    string
    Description

    The phone number for the contact.

Optional attributes

  • Name
    avatar_url
    Type
    string
    Description

    The avatar image URL for the contact.

  • Name
    display_name
    Type
    string
    Description

    The contact display name in the contact list. By default, this is just the username.

Request

POST
/v1/contacts
curl https://api.protocol.chat/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d username="FrankMcCallister" \
  -d phone_number="1-800-759-3000" \
  -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": null,
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": null,
  "created_at": 692233200
}
GET/v1/customer/:id

Retrieve a customer

This endpoint allows you to retrieve a contact by providing their Protocol id. Refer to the list at the top of this page to see which properties are included with contact objects.

Request

GET
/v1/contacts/WAz8eIbvDR60rouK
curl https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": null,
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": 705103200,
  "created_at": 692233200
}
POST/v1/contacts/:id

Update a customer

This endpoint allows you to perform an update on a contact. Currently, the only attribute that can be updated on contacts is the display_name attribute which controls how a contact appears in your contact list in Protocol.

Optional attributes

  • Name
    display_name
    Type
    string
    Description

    The contact display name in the contact list. By default, this is just the username.

Request

PUT
/v1/contacts/WAz8eIbvDR60rouK
curl -X PUT https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d display_name="UncleFrank"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": "UncleFrank",
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": 705103200,
  "created_at": 692233200
}
GET/v1/customer

List customers

This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page.

Optional attributes

  • Name
    limit
    Type
    integer
    Description

    Limit the number of contacts returned.

Request

GET
/v1/contacts
curl -G https://api.protocol.chat/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d active=true \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "WAz8eIbvDR60rouK",
      "username": "FrankMcCallister",
      "phone_number": "1-800-759-3000",
      "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
      "display_name": null,
      "conversation_id": "xgQQXg3hrtjh7AvZ",
      "last_active_at": 705103200,
      "created_at": 692233200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

Was this page helpful?