Find Customers

POST

companies

{company_id}

customers

find

Find Customers

curl --request POST \
  --url https://api.maplebilling.com/api/v1/companies/{company_id}/customers/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 20
  },
  "include_meta": true,
  "query": {
    "email": "<unknown>",
    "exclude_from_metrics": "<unknown>",
    "has_parent": "<unknown>",
    "identifier": "<unknown>",
    "managed_externally": "<unknown>",
    "mrr": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "name": "<unknown>",
    "org_name": "<unknown>",
    "owner_id": "<string>",
    "owner_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "parent_customer_id": "<string>",
    "phone": "<unknown>",
    "search": "<unknown>",
    "status": "ACTIVE",
    "statuses": "ACTIVE",
    "tags": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "title": "<unknown>"
  },
  "sort_key": "createdAtDesc"
}
'

{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 123
  },
  "results": [
    {
      "address": {
        "address_line_1": "<string>",
        "address_line_2": "<string>",
        "city": "<string>",
        "country": "<string>",
        "place_id": "<unknown>",
        "state": "<string>",
        "zip": "<string>"
      },
      "arr": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "billing_emails": [
        "<string>"
      ],
      "company_id": "<string>",
      "computed_entitlements": [
        {
          "entitlement_id": "<string>",
          "id": "<string>",
          "inherited_from_id": "<unknown>",
          "inherited_from_type": "<unknown>",
          "key": "<string>",
          "name": "<string>",
          "original_value": "<unknown>",
          "overridden": "<unknown>",
          "type": "<string>",
          "value": "<unknown>"
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "customer_integration_metadata": {},
      "email": "<string>",
      "exclude_from_metrics": true,
      "id": "<string>",
      "identifier": "<string>",
      "integration_references": [
        {
          "integration_icon": "<string>",
          "integration_id": "<string>",
          "integration_key": "<string>",
          "integration_name": "<string>",
          "reference_type": "<string>",
          "remote_id": "<string>",
          "remote_type": "<string>"
        }
      ],
      "locale": "<string>",
      "managed_externally": true,
      "metadata": {},
      "mrr": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "name": "<string>",
      "org_name": "<string>",
      "owner_id": "<unknown>",
      "parent_customer_id": "<unknown>",
      "phone": "<string>",
      "status": "<string>",
      "title": "<string>",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

The idempotency key that will be used to ensure the request is only performed once

Path Parameters

company_id

string

required

The company ID with the prefix 'cmp_'.

Body

application/json

pagination

object

required

The pagination parameters for the request

Show child attributes

pagination.from_key

null | string

pagination.limit

integer<int64>

default:20

Required range: 0 <= x <= 200

include_meta

boolean | null

Whether to include additional metadata in the pagination response such the number of total results

query

object

The query criteria for the request

Show child attributes

query.email

null | string

The email of the customer

query.exclude_from_metrics

null | boolean

Whether the customer is excluded from metrics or not

query.has_parent

null | boolean

Whether this customer has a parent or not

query.identifier

null | string

The identifier of the customer that ties them back to your system

query.managed_externally

null | boolean

Whether the customer is managed customer outside of Maple

query.mrr

object

Filter based on MRR ranges

Show child attributes

query.mrr.eq

null | number

Equal to

query.mrr.gt

null | number

Greater than

query.mrr.gte

null | number

Greater than or equal to

query.mrr.lte

null | number

Less than or equal to

query.name

null | string

The name of the customer

query.org_name

null | string

The org name of the customer

query.owner_id

string | null

The company user ID of the user in Maple that is assigned to manage this customer

query.owner_ids

object

The company user ID of the user in Maple that is assigned to manage this customer

Show child attributes

query.owner_ids.condition

enum<string>

required

Available options:

AND,

OR

query.owner_ids.values

string[]

required

query.parent_customer_id

string | null

The parent customer ID of the customer

query.phone

null | string

The phone number of the customer

query.search

null | string

Any search string to match customers

query.status

null | enum<string>

The specific status of the customer that can be one of ACTIVE or ARCHIVED

Available options:

ACTIVE,

ARCHIVED

query.statuses

string[] | null

The status of the customers that can include ACTIVE and ARCHIVED

query.tags

object

The tags of the customer

Show child attributes

query.tags.condition

enum<string>

required

Available options:

AND,

OR

query.tags.values

string[]

required

query.title

null | string

The title of the customer

sort_key

enum<string>

default:createdAtDesc

Available options:

createdAtDesc,

createdAtAsc,

updatedAtAsc,

updatedAtDesc,

aToZ,

zToA,

mrrAsc,

mrrDesc,

orgAToZ,

orgZToA

Response

200 - application/json

pagination

object

Show child attributes

pagination.from_key

null | string

pagination.limit

integer<int64>

results

object[] | null

Show child attributes

results.address

object

The address of the customer

Show child attributes

results.address.address_line_1

string

results.address.address_line_2

string

results.address.city

string

results.address.country

string

2-character country code (ISO 3166-1 alpha-2)

results.address.place_id

null | string

results.address.state

string

results.address.zip

string

results.arr

object

The ARR of the customer

Show child attributes

results.arr.currency

string

results.arr.value_in_cents

integer<int64>

results.billing_emails

string[] | null

The additional emails to cc on customer's invoices

results.company_id

string

The company ID of the customer

results.computed_entitlements

object[] | null

The computed entitlements for the customer

Show child attributes

results.computed_entitlements.entitlement_id

string

results.computed_entitlements.id

string

results.computed_entitlements.inherited_from_id

null | string

results.computed_entitlements.inherited_from_type

null | string

results.computed_entitlements.key

string

results.computed_entitlements.name

string

results.computed_entitlements.original_value

any

results.computed_entitlements.overridden

null | boolean

results.computed_entitlements.type

string

results.computed_entitlements.value

any

results.created_at

string<date-time>

The date the customer was created

results.customer_integration_metadata

object

Show child attributes

results.customer_integration_metadata.{key}

object

Show child attributes

results.customer_integration_metadata.{key}.avalara

object

Show child attributes

results.customer_integration_metadata.{key}.avalara.entity_code

string

results.email

string

The email of the customer

results.exclude_from_metrics

boolean

Whether to exclude this customer and related fields from any metrics in Maple

results.id

string

The ID of the customer in Maple

results.identifier

string

The unique identifier for the customer that ties back to your system. You can query for a customer using this identifier

results.integration_references

object[]

The integration references of this customer in third-party applications connected to Maple

Show child attributes

results.integration_references.integration_icon

string

results.integration_references.integration_id

string

results.integration_references.integration_key

string

results.integration_references.integration_name

string

results.integration_references.reference_type

string

results.integration_references.remote_id

string

results.integration_references.remote_type

string

results.locale

string

The locale of the customer

results.managed_externally

boolean

Whether this customer is managed outside of Maple

results.metadata

object

The metadata as key-value pairs attached to this customer

results.mrr

object

The MRR of the customer

Show child attributes

results.mrr.currency

string

results.mrr.value_in_cents

integer<int64>

results.name

string

The name of the customer

results.org_name

string

The name of the company or the organization this customer is a part of

results.owner_id

null | string

The company user ID of person in Maple assigned to manage this customer

results.parent_customer_id

null | string

The customer ID of the parent customer assigned in Maple

results.phone

string

The phone number of the customer

results.status

string

The status of the customer such as ACTIVE or ARCHIVED

results.title

string

The title of the customer, such as CEO, VP

results.updated_at

string<date-time>

The date the customer was last updated

Get CustomerRetrieve a customer by ID or external identifier

⌘I

Find Customers

curl --request POST \
  --url https://api.maplebilling.com/api/v1/companies/{company_id}/customers/find \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 20
  },
  "include_meta": true,
  "query": {
    "email": "<unknown>",
    "exclude_from_metrics": "<unknown>",
    "has_parent": "<unknown>",
    "identifier": "<unknown>",
    "managed_externally": "<unknown>",
    "mrr": {
      "eq": "<unknown>",
      "gt": "<unknown>",
      "gte": "<unknown>",
      "lte": "<unknown>"
    },
    "name": "<unknown>",
    "org_name": "<unknown>",
    "owner_id": "<string>",
    "owner_ids": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "parent_customer_id": "<string>",
    "phone": "<unknown>",
    "search": "<unknown>",
    "status": "ACTIVE",
    "statuses": "ACTIVE",
    "tags": {
      "condition": "AND",
      "values": [
        "<string>"
      ]
    },
    "title": "<unknown>"
  },
  "sort_key": "createdAtDesc"
}
'

{
  "pagination": {
    "from_key": "<unknown>",
    "limit": 123
  },
  "results": [
    {
      "address": {
        "address_line_1": "<string>",
        "address_line_2": "<string>",
        "city": "<string>",
        "country": "<string>",
        "place_id": "<unknown>",
        "state": "<string>",
        "zip": "<string>"
      },
      "arr": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "billing_emails": [
        "<string>"
      ],
      "company_id": "<string>",
      "computed_entitlements": [
        {
          "entitlement_id": "<string>",
          "id": "<string>",
          "inherited_from_id": "<unknown>",
          "inherited_from_type": "<unknown>",
          "key": "<string>",
          "name": "<string>",
          "original_value": "<unknown>",
          "overridden": "<unknown>",
          "type": "<string>",
          "value": "<unknown>"
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "customer_integration_metadata": {},
      "email": "<string>",
      "exclude_from_metrics": true,
      "id": "<string>",
      "identifier": "<string>",
      "integration_references": [
        {
          "integration_icon": "<string>",
          "integration_id": "<string>",
          "integration_key": "<string>",
          "integration_name": "<string>",
          "reference_type": "<string>",
          "remote_id": "<string>",
          "remote_type": "<string>"
        }
      ],
      "locale": "<string>",
      "managed_externally": true,
      "metadata": {},
      "mrr": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "name": "<string>",
      "org_name": "<string>",
      "owner_id": "<unknown>",
      "parent_customer_id": "<unknown>",
      "phone": "<string>",
      "status": "<string>",
      "title": "<string>",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ]
}

API Features

API Reference

Webhook Reference

Authorizations

Headers

Path Parameters

Body

Response