Charthop customer API
The customer API from Charthop — 4 operation(s) for customer.
OpenAPI Specification
swagger: '2.0'
info:
description: REST API for ChartHop
version: V1.0.0
title: ChartHop access customer API
contact:
name: ChartHop
url: https://www.charthop.com
email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: customer
paths:
/v1/customer:
get:
tags:
- customer
summary: Return all visible customers, paginated by name
operationId: findCustomers
consumes:
- application/json
produces:
- application/json
parameters:
- name: from
in: query
description: Customer id to start from
required: false
type: string
- name: limit
in: query
description: Number of results to return
required: false
type: integer
format: int32
- name: status
in: query
description: Customer.Status. (ACTIVE/INACTIVE/TRAIL)
required: false
type: string
- name: trialAsOf
in: query
description: Only return customers with a product trial in progress as of this date (range inclusive)
required: false
type: string
format: date
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/ResultsCustomer'
'400':
description: bad request
'404':
description: not found
post:
tags:
- customer
summary: Create a new customer
operationId: createCustomer
consumes:
- application/json
produces:
- application/json
parameters:
- name: body
in: body
description: Customer data to create
required: true
schema:
$ref: '#/definitions/CreateCustomer'
responses:
'201':
description: customer created
schema:
$ref: '#/definitions/Customer'
'400':
description: invalid data
'401':
description: not authorized
'403':
description: permission denied
/v1/customer/{customerId}:
get:
tags:
- customer
summary: Return a particular customer by id
operationId: getCustomer
consumes:
- application/json
produces:
- application/json
parameters:
- name: customerId
in: path
description: Customer id
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Customer'
'400':
description: bad request
'404':
description: not found
patch:
tags:
- customer
summary: Update an existing customer
operationId: updateCustomer
consumes:
- application/json
produces:
- application/json
parameters:
- name: customerId
in: path
description: Customer id
required: true
type: string
- name: body
in: body
description: Customer data to update
required: true
schema:
$ref: '#/definitions/UpdateCustomer'
responses:
'204':
description: customer updated
'400':
description: invalid data
'401':
description: not authorized
'403':
description: permission denied
'404':
description: not found
/v1/customer/{customerId}/invoices:
get:
tags:
- customer
summary: Returns a list of all the invoices for the given customer
operationId: getCustomerInvoices
consumes:
- application/json
produces:
- application/json
parameters:
- name: customerId
in: path
description: Customer id
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/InvoiceResponse'
'400':
description: bad request
'404':
description: not found
/v1/customer/{customerId}/subscription:
get:
tags:
- customer
summary: Returns information about the Charthop subscription for the given customer
operationId: getCharthopSubscription
consumes:
- application/json
produces:
- application/json
parameters:
- name: customerId
in: path
description: Customer id
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Subscription'
'400':
description: bad request
'404':
description: not found
patch:
tags:
- customer
summary: Update a subscription on a customer
operationId: updateSubscription
consumes:
- application/json
produces:
- application/json
parameters:
- name: customerId
in: path
description: Customer id
required: true
type: string
- name: body
in: body
description: Subscription data to update
required: true
schema:
$ref: '#/definitions/UpdateSubscription'
responses:
'204':
description: successful operation
'400':
description: invalid data
'401':
description: not authorized
'403':
description: permission denied
'404':
description: not found
definitions:
Address:
type: object
required:
- country
properties:
street1:
type: string
description: street address, line 1
example: 123 Anywhere Street
minItems: 0
maxItems: 200
street2:
type: string
description: street address, line 2
example: Apt 6L
minItems: 0
maxItems: 200
street3:
type: string
description: street address, line 3
example: Sixth Floor
minItems: 0
maxItems: 200
city:
type: string
description: city
example: New York
minItems: 0
maxItems: 80
state:
type: string
description: state
example: NY
minItems: 0
maxItems: 80
country:
type: string
description: country (two-digit ISO code)
example: NY
pattern: ^[A-Z]{2}$
postal:
type: string
description: postal code
example: '10001'
minItems: 0
maxItems: 10
geo:
description: geopoint location
$ref: '#/definitions/Geopoint'
approxGeo:
description: approximate geopoint location (suitable for a map placement, but not exact location)
$ref: '#/definitions/Geopoint'
Customer:
type: object
required:
- id
- name
- status
properties:
id:
type: string
description: unique id of customer
example: 588f7ee98f138b19220041a7
name:
type: string
description: name of customer
email:
type: string
description: email address for billing purposes
billAddress:
description: mailing address for billing purposes
$ref: '#/definitions/Address'
industry:
type: string
description: industry that customer is in
source:
type: string
description: source of customer signup
enum:
- ADP_MARKETPLACE
- SELF_SERVE
- SELF_SERVE_TEST
- SEQUOIA_ONE
- CONNECT
status:
type: string
description: current status
enum:
- ACTIVE
- INACTIVE
- TRIAL
- CHURN
- PAYMENT_ERROR
stripeCustomerId:
type: string
description: stripe customer id
salesforceAccountId:
type: string
description: salesforce account id
pattern: ^[a-zA-Z0-9]{15}|[a-zA-Z0-9]{18}$
products:
type: array
description: products that this customer has purchased
items:
$ref: '#/definitions/ProductItem'
trialProducts:
type: array
description: products this customer has temporary trial access to, each bounded by a date range
items:
$ref: '#/definitions/TrialProduct'
restrictedFeatures:
type: array
description: features that are restricted for the customer
items:
type: string
enum:
- AI_ACTION
- AI_AGENT
- AI_API_WRITE
- AI_SLACK_TEAM_CHAT
- ATS_SYNC
- BUDGET
- COMPENSATION_REVIEW
- CUSTOM_CALENDAR
- CUSTOM_FIELD
- CUSTOM_FIELD_READONLY
- CUSTOM_FORM
- CUSTOM_PROFILE_TAB
- CUSTOM_ROLE
- FORM_ANONYMOUS
- FORM_RELEASE
- FORM_SIGNATURE
- GOAL
- MULTI_PAYROLL
- PERFORMANCE_REVIEW
- REPORT
- REPORT_READONLY
- SCENARIO
- SIGNATURE
- SIGNATURE_QES
- SIMPLE_WORKFLOWS
- SURVEY
- TABLE
- TEMPLATE
- WORKDAY_ADAPTIVE
- PAYROLL_OUTBOUND
- APPROVAL_WORKFLOWS
- CONTENT
- IDENTITY_OUTBOUND
- ONBOARDING_OFFBOARDING
- TIMEOFF
featureOptionOverrides:
type: array
description: override feature options for the customer
items:
$ref: '#/definitions/FeatureAccessOption'
startDate:
type: string
format: date
description: initial date of billing
endDate:
type: string
format: date
description: end of service date for churning customers -- on or after this date, service should be disabled
nextInvoiceDate:
type: string
format: date
description: date of next invoice
orgCount:
type: integer
format: int32
description: number of orgs covered by this customer
primaryHeadCount:
type: integer
format: int32
description: number of total headcount across all orgs
secondaryHeadCount:
type: integer
format: int32
description: number of total headcount across all orgs
tertiaryHeadCount:
type: integer
format: int32
description: number of total headcount across all orgs
primaryHeadCountFilter:
type: string
description: primary headcount filter - used for billing purposes
secondaryHeadCountFilter:
type: string
description: secondary headcount filter - used for billing purposes
tertiaryHeadCountFilter:
type: string
description: tertiary headcount filter - used for billing purposes
arr:
type: number
description: current ARR of the customer based on most recent invoice
trialStartDate:
type: string
format: date
description: date this customer begins their trial period
trialEndDate:
type: string
format: date
description: date this customer ends their trial period
stripeSubscriptionSync:
type: string
description: Stripe subscription settings
enum:
- SYNC
- DELETE
createAt:
type: string
description: created timestamp
example: '2017-01-24T13:57:52Z'
createId:
type: string
description: created by
example: 588f7ee98f138b19220041a7
createBehalfId:
type: string
description: created on behalf of user id
example: 588f7ee98f138b19220041a7
createAttribution:
$ref: '#/definitions/Attribution'
updateAt:
type: string
description: updated timestamp
example: '2017-01-24T13:57:52Z'
updateId:
type: string
description: updated by
example: 588f7ee98f138b19220041a7
updateBehalfId:
type: string
description: last updated on behalf of user id
example: 588f7ee98f138b19220041a7
updateAttribution:
$ref: '#/definitions/Attribution'
Invoice:
type: object
required:
- number
- amount
- status
- createAt
properties:
number:
type: string
description: a unique identifying string for invoices
example: F38A6C8-0010
amount:
type: number
description: current final amount due for the invoices
example: '1002.31'
hostedInvoiceUrl:
type: string
description: URL for the hosted invoice page, which allows customers to view and pay an invoice
example: https://pay.stripe.com/invoice/invst_Nv8DFERQvTsBJqnZ4z19cGZBU1
invoicePdf:
type: string
description: the link to download the PDF for the invoice
example: https://pay.stripe.com/invoice/invst_wNK0BvV4iUOWOn5mzLT1ybQ2LC/pdf
status:
type: string
description: one of PAID, UNPAID, or VOID
example: PAID
enum:
- PAID
- UNPAID
- VOID
createAt:
type: string
description: created timestamp
example: '2019-07-27T20:56:10Z'
FeatureAccessOption:
type: object
required:
- name
- type
properties:
name:
type: string
description: The name of the feature option tied to the feature access
example: smart_fields
enum:
- CONFIGURED_ROLES
- SMART_FIELDS
- APP_FIELD_MAPPERS
- MULTI_PAYROLL_INSTALLS
description:
type: string
description: The description of the feature option
type:
type: string
description: The feature option type
enum:
- LIMIT
- FULL_ACCESS
limit:
type: integer
format: int32
description: The feature option limit
PaymentInfo:
type: object
required:
- paymentType
properties:
paymentType:
type: string
description: indicates how the customer has decided to pay; one of CREDIT_CARD, INVOICE
example: CREDIT_CARD
enum:
- CREDIT_CARD
- INVOICE
creditCardEndDigits:
type: string
description: if the customer has indicated they wish to pay by credit card, the last four digits of the credit card they are paying with. Null if the customer is paying by invoice.
example: '4242'
brand:
type: string
description: if the customer has indicated they wish to pay by credit card, the brand of the credit card they are paying with. Null if the customer is paying by invoice.
example: Visa
Subscription:
type: object
required:
- nextInvoiceAt
- plan
- paymentInfo
properties:
nextInvoiceAt:
type: string
description: Timestamp when the next invoice will be generated
example: '2019-07-27T20:56:10Z'
plan:
description: Plan this subscription is for
$ref: '#/definitions/Plan'
paymentInfo:
description: Information about how the customer pays for this subscription
$ref: '#/definitions/PaymentInfo'
AccessAction:
type: object
required:
- action
properties:
action:
type: string
fields:
type: array
uniqueItems: true
items:
type: string
types:
type: array
uniqueItems: true
items:
type: string
InvoiceResponse:
type: object
required:
- invoices
properties:
invoices:
type: array
items:
$ref: '#/definitions/Invoice'
CreateCustomer:
type: object
required:
- name
- email
- startDate
properties:
name:
type: string
description: name of customer
email:
type: string
description: email address for billing purposes
billAddress:
description: mailing address for billing purposes
$ref: '#/definitions/Address'
industry:
type: string
description: industry that customer is in
source:
type: string
description: source of customer signup
enum:
- ADP_MARKETPLACE
- SELF_SERVE
- SELF_SERVE_TEST
- SEQUOIA_ONE
- CONNECT
status:
type: string
description: current status
enum:
- ACTIVE
- INACTIVE
- TRIAL
- CHURN
- PAYMENT_ERROR
salesforceAccountId:
type: string
description: salesforce account id
pattern: ^[a-zA-Z0-9]{15}|[a-zA-Z0-9]{18}$
products:
type: array
description: products that this customer has purchased
items:
$ref: '#/definitions/ProductItem'
trialProducts:
type: array
description: products this customer has temporary trial access to, each bounded by a date range
items:
$ref: '#/definitions/TrialProduct'
restrictedFeatures:
type: array
description: features that are restricted for the customer
items:
type: string
enum:
- AI_ACTION
- AI_AGENT
- AI_API_WRITE
- AI_SLACK_TEAM_CHAT
- ATS_SYNC
- BUDGET
- COMPENSATION_REVIEW
- CUSTOM_CALENDAR
- CUSTOM_FIELD
- CUSTOM_FIELD_READONLY
- CUSTOM_FORM
- CUSTOM_PROFILE_TAB
- CUSTOM_ROLE
- FORM_ANONYMOUS
- FORM_RELEASE
- FORM_SIGNATURE
- GOAL
- MULTI_PAYROLL
- PERFORMANCE_REVIEW
- REPORT
- REPORT_READONLY
- SCENARIO
- SIGNATURE
- SIGNATURE_QES
- SIMPLE_WORKFLOWS
- SURVEY
- TABLE
- TEMPLATE
- WORKDAY_ADAPTIVE
- PAYROLL_OUTBOUND
- APPROVAL_WORKFLOWS
- CONTENT
- IDENTITY_OUTBOUND
- ONBOARDING_OFFBOARDING
- TIMEOFF
featureOptionOverrides:
type: array
description: override feature options for the customer
items:
$ref: '#/definitions/FeatureAccessOption'
startDate:
type: string
format: date
description: initial date of billing
endDate:
type: string
format: date
description: end of service date for churning customers -- on or after this date, service should be disabled
nextInvoiceDate:
type: string
format: date
description: date of next invoice
primaryHeadCountFilter:
type: string
description: primary headcount filter - used for billing purposes
secondaryHeadCountFilter:
type: string
description: secondary headcount filter - used for billing purposes
tertiaryHeadCountFilter:
type: string
description: tertiary headcount filter - used for billing purposes
arr:
type: number
description: current ARR of the customer based on most recent invoice
trialStartDate:
type: string
format: date
description: date this customer begins their trial period
trialEndDate:
type: string
format: date
description: date this customer ends their trial period
stripeSubscriptionSync:
type: string
description: Stripe subscription settings
enum:
- SYNC
- DELETE
Geopoint:
type: object
required:
- type
- coordinates
properties:
type:
type: string
description: Type of point
readOnly: true
coordinates:
type: array
description: The longitude and latitude of the point
readOnly: true
items:
type: number
format: double
Attribution:
type: object
properties:
principalUserId:
type: string
example: 588f7ee98f138b19220041a7
agentUserIds:
type: array
items:
type: string
example: 588f7ee98f138b19220041a7
eventId:
type: string
example: 588f7ee98f138b19220041a7
aiChatId:
type: string
example: 588f7ee98f138b19220041a7
aiToolUseId:
type: string
channel:
type: string
enum:
- WEB
- MOBILE
- SLACK
- TEAMS
- MCP
ResultsAccess:
type: object
required:
- allowed
properties:
ids:
type: array
uniqueItems: true
items:
type: string
example: 588f7ee98f138b19220041a7
allowed:
type: array
uniqueItems: true
items:
$ref: '#/definitions/AccessAction'
UpdateCustomer:
type: object
properties:
name:
type: string
description: name of customer
email:
type: string
description: email address for billing purposes
billAddress:
description: mailing address for billing purposes
$ref: '#/definitions/Address'
industry:
type: string
description: industry that customer is in
source:
type: string
description: source of customer signup
enum:
- ADP_MARKETPLACE
- SELF_SERVE
- SELF_SERVE_TEST
- SEQUOIA_ONE
- CONNECT
status:
type: string
description: current status
enum:
- ACTIVE
- INACTIVE
- TRIAL
- CHURN
- PAYMENT_ERROR
salesforceAccountId:
type: string
description: salesforce account id
pattern: ^[a-zA-Z0-9]{15}|[a-zA-Z0-9]{18}$
products:
type: array
description: products that this customer has purchased
items:
$ref: '#/definitions/ProductItem'
trialProducts:
type: array
description: products this customer has temporary trial access to, each bounded by a date range
items:
$ref: '#/definitions/TrialProduct'
restrictedFeatures:
type: array
description: features that are restricted for the customer
items:
type: string
enum:
- AI_ACTION
- AI_AGENT
- AI_API_WRITE
- AI_SLACK_TEAM_CHAT
- ATS_SYNC
- BUDGET
- COMPENSATION_REVIEW
- CUSTOM_CALENDAR
- CUSTOM_FIELD
- CUSTOM_FIELD_READONLY
- CUSTOM_FORM
- CUSTOM_PROFILE_TAB
- CUSTOM_ROLE
- FORM_ANONYMOUS
- FORM_RELEASE
- FORM_SIGNATURE
- GOAL
- MULTI_PAYROLL
- PERFORMANCE_REVIEW
- REPORT
- REPORT_READONLY
- SCENARIO
- SIGNATURE
- SIGNATURE_QES
- SIMPLE_WORKFLOWS
- SURVEY
- TABLE
- TEMPLATE
- WORKDAY_ADAPTIVE
- PAYROLL_OUTBOUND
- APPROVAL_WORKFLOWS
- CONTENT
- IDENTITY_OUTBOUND
- ONBOARDING_OFFBOARDING
- TIMEOFF
featureOptionOverrides:
type: array
description: override feature options for the customer
items:
$ref: '#/definitions/FeatureAccessOption'
startDate:
type: string
format: date
description: initial date of billing
endDate:
type: string
format: date
description: end of service date for churning customers -- on or after this date, service should be disabled
nextInvoiceDate:
type: string
format: date
description: date of next invoice
primaryHeadCountFilter:
type: string
description: primary headcount filter - used for billing purposes
secondaryHeadCountFilter:
type: string
description: secondary headcount filter - used for billing purposes
tertiaryHeadCountFilter:
type: string
description: tertiary headcount filter - used for billing purposes
arr:
type: number
description: current ARR of the customer based on most recent invoice
trialStartDate:
type: string
format: date
description: date this customer begins their trial period
trialEndDate:
type: string
format: date
description: date this customer ends their trial period
stripeSubscriptionSync:
type: string
description: Stripe subscription settings
enum:
- SYNC
- DELETE
Plan:
type: object
required:
- id
- name
- interval
- intervalCount
- tiers
- stripeProductId
properties:
id:
type: string
description: unique Stripe identifier for this plan
name:
type: string
description: human-readable nickname for this plan
interval:
type: string
description: interval for billing on this plan
enum:
- DAY
- WEEK
- MONTH
- YEAR
intervalCount:
type: integer
format: int32
description: number of intervals, for example 3 for quarterly billing
tiers:
type: array
description: pricing tiers, per employee per interval
items:
$ref: '#/definitions/PlanTier'
stripeProductId:
type: string
description: stripe product id that this plan belongs to
PlanTier:
type: object
required:
- unitAmount
properties:
upTo:
type: integer
format: int64
description: headcount up to this level is charged at the below rate
unitAmount:
type: number
description: PEPM rate
UpdateSubscription:
type: object
required:
- paymentMethod
properties:
paymentMethod:
type: string
description: Payment method to create; 'INVOICE' to make subscription paid by invoice, or the ID of the payment method if to make the subscription automatically charge a card
TrialProduct:
type: object
required:
- productId
- startDate
- endDate
properties:
productId:
type: string
description: id of the product the customer is trialing
example: 588f7ee98f138b19220041a7
startDate:
type: string
format: date
description: first date the trial grants access (inclusive)
endDate:
type: string
format: date
description: last date the trial grants access (inclusive)
ResultsCustomer:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/definitions/Customer'
next:
type: string
access:
type: array
items:
$ref: '#/definitions/ResultsAccess'
ProductItem:
type: object
required:
- productId
- stripePriceId
properties:
productId:
type: string
example: 588f7ee98f138b19220041a7
stripePriceId:
type: string