openapi: 3.0.0
info:
title: CustomerApi
description: >-
All endpoints are rate limited per organization — 120 requests/min by default, 30/min for
/getActivities — and return HTTP 429 when the limit is exceeded.
An API key belongs to your organization, not to a person, so no user's visibility applies.
It returns your organization's conversations except those marked private: list endpoints
leave them out, along with their scorecards, listens, coaching feedback and comments, and
endpoints that take an activityId answer 404 (not available to your organization) for a
private conversation. Automated reports follow what the report's creator can see in
Jiminny, so they can include private conversations the creator organised, took part in,
or had shared with them.
version: 1.3.0
servers:
- url: https://app.jiminny.com/customer/api/v1
description: Production US app server (uses live data)
- url: https://app.jiminny.eu/customer/api/v1
description: Production EU app server (uses live data)
paths:
/me:
get:
summary: Return the current authenticated Organization
tags:
- "Organization"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Organization
content:
application/json:
schema:
$ref: "#/components/schemas/Organization"
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
/webhooks:
get:
summary: List the webhooks registered for your team
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Array of webhooks registered for the authenticated organization.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Webhook'
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
tags:
- "Webhook"
post:
summary: Create a webhook
description: No webhook is sent about a private conversation, whatever the trigger.
tags:
- "Webhook"
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- trigger
- url
properties:
trigger:
$ref: "#/components/schemas/WebhookTrigger"
url:
type: string
format: uri
maxLength: 191
description: The destination URL to receive the webhook
example: "https://example.com/webhooks"
external_id:
type: string
maxLength: 191
nullable: true
example: "external-uuid-123"
description: Sent as snake_case external_id, but read back as externalId
from GET /webhooks.
origin:
type: string
enum: [jiminny, zapier, customer]
description: Origin tag for the webhook. Defaults to customer.
configuration:
type: object
nullable: true
description: Optional provider-specific configuration (a JSON array is also
accepted).
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'201':
description: Webhook successfully created.
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
example: "a3f66e54-04b2-4db6-b4e3-60b88e6e4384"
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: >-
Input validation failed. Note the url must be publicly resolvable
(private/internal addresses are rejected), and this operation has two distinct
422 bodies — Laravel's {message, errors} from field validation, and a string-error
{"error": "..."} from the creation service.
delete:
summary: Delete a webhook
tags:
- "Webhook"
parameters:
- name: id
in: query
required: true
schema:
type: string
format: uuid
description: UUID of the webhook to delete.
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Webhook successfully deleted.
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: Input validation failed — including an unknown webhook id or one
not available to your organization (validated as existence, so never a 404).
/webhookSample:
get:
summary: Get a webhook sample payload
description: Built from your organization's most recent public conversation; a private one is never used.
tags:
- "Webhook"
parameters:
- name: trigger
in: query
required: true
schema:
$ref: "#/components/schemas/WebhookTrigger"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: A one-element array wrapping the sample payload object. An unresolvable
trigger, or an organization with no public conversation to build the sample from,
yields a single empty element rather than an error.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: Input validation failed — trigger is required and must be one of the
WebhookTrigger values.
/getTranscription:
get:
description: Get transcription segments for a given activity.
tags:
- "Transcript"
parameters:
- name: 'activityId'
in: query
description: The activity uuid you wish to retrieve the transcription for.
required: true
schema:
type: string
format: "uuid"
example: "7efa9c4f-9c47-4922-9ae7-e61a3dbecd72"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: 'Input validation failed — including an activityId that is not a known, valid
activity id'
content:
'application/json':
schema:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
properties:
activityId:
type: array
items:
type: string
example: "The selected activity id is invalid."
'404':
description: 'The activity is not available to your organization.'
'200':
description: 'List of transcript segments.'
content:
'application/json':
schema:
type: array
items:
allOf:
- $ref: '#/components/schemas/TranscriptSegment'
/getSummary:
get:
description: >
Gets summary data based on activityId. In the `text` format an ampersand surrounded by
spaces is returned as the word "and", so that consumers which HTML-escape the text before
displaying it do not show "&". Ampersands inside abbreviations such as "R&D" are
returned unchanged.
tags:
- "Transcription summary"
parameters:
- name: 'activityId'
in: query
required: true
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
- name: 'format'
in: query
required: false
description: Plain text (default) or HTML, where the summary is wrapped in `` and
`
`. An unsupported value returns 422.
schema:
type: string
enum: [text, html]
default: text
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: 'Input parameters error'
content:
'application/json':
schema:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
properties:
activityId:
type: array
items:
type: string
example: "The selected activity id is invalid."
'204':
description: 'There is no summary available and none is coming. No response body.'
'404':
description: 'The activity is not available to your organization, or the summary is still being
generated — poll again shortly.'
content:
'application/json':
schema:
type: object
properties:
error:
type: string
example: "Summary is being generated. Please check again shortly."
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: object
properties:
summary:
type: object
properties:
content:
type: string
example: "John Doe mentions that it's been an impactful quarter. Jane Doe notes that they'd love to recap."
/getTriggers:
get:
description: Gets topic triggers data based on team. Team is taken from authentication.
tags:
- "Topic triggers"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: "array"
items:
type: "object"
properties:
title:
type: "string"
example: "Tech Stack"
uuid:
type: "string"
example: "367e40ad-d93b-4bd1-9192-53316c1f3717"
color:
type: "string"
example: "#FF94CD"
orderIndex:
type: "integer"
example: 0
children:
type: "array"
items:
type: "object"
properties:
title:
type: "string"
example: "Tech Stack"
uuid:
type: "string"
example: "367e40ad-d93b-4bd1-9192-53316c1f3717"
orderIndex:
type: "integer"
example: 0
children:
type: "array"
items:
type: "object"
properties:
title:
type: "string"
example: "Tech Stack"
uuid:
type: "string"
example: "367e40ad-d93b-4bd1-9192-53316c1f3717"
saidBy:
type: "string"
example: "anyone"
language:
type: "string"
example: "en"
orderIndex:
type: "integer"
example: 0
/getMatchedTriggers:
get:
description: Gets topic triggers data based on activity.
tags:
- "Topic triggers"
parameters:
- name: 'activityId'
in: query
required: true
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: 'Input parameters error'
content:
'application/json':
schema:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
properties:
activityId:
type: array
items:
type: string
example: "The selected activity id is invalid."
'404':
description: 'The activity is not available to your organization.'
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: "array"
items:
type: "object"
properties:
theme:
type: "object"
properties:
id:
type: "string"
example: "ecaa6633-37d5-4797-89f0-433463d29ef6"
color:
type: "string"
example: "#AE3EC9"
title:
type: "string"
example: "Discovery Excellence"
topic:
type: "object"
properties:
id:
type: "string"
example: "83c5a422-04de-4570-9ec1-abe8e5bf65e8"
title:
type: "string"
example: "Economic Buyer"
trigger:
type: "object"
properties:
id:
type: "string"
example: "55f4fa85-08a1-41be-9947-0b6b07365af1"
title:
type: "string"
example: "decision maker"
startsAt:
type: "number"
example: 104.56
endsAt:
type: "number"
example: 129.3
participantId:
type: "string"
example: "0d92b3c2-02fd-4c12-aacd-2c935b59ba36"
text:
type: "string"
example: "Now that doesn't mean that they're not interested in your service, it means that they're just shopping the market for other competitors. So with our technology we can show you those companies at the exact moment they're in the market and provide you with a phone number, an email, and a specific contact person, like a decision maker that you can open up a conversation with. Now all I was going to do today on the call is just I wanted to learn a little bit more about your company."
/getUsers:
get:
description: Gets users data based on team. Responses are cached for up to one hour —
very recent user or team changes may take up to an hour to appear. Team is taken from authentication.
tags:
- "Users"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: object
properties:
data:
type: "array"
items:
type: "object"
properties:
id:
type: "string"
example: "0d92b3c2-02fd-4c12-aacd-2c935b59ba36"
name:
type: "string"
example: "John Doe"
email:
type: "string"
example: "john.doe@jiminny.com"
status:
type: "integer"
enum:
- 1
- 2
teamName:
type: "string"
example: "Sales"
teamID:
type: "string"
format: uuid
description: UUID of the user's team (the same "team" the
automated-reports share gate refers to).
crmID:
type: "string"
nullable: true
example: "00546000000fN9vAAE"
roles:
type: "array"
items:
type: "string"
example: "Admin"
links:
type: "object"
properties:
self:
type: "string"
example: "https://app.dev.jiminny.com/customer/api/v1/getUsers"
/getActivities:
get:
description: Get activities data based on filters. Returns only completed and processed activities. All date-time values are UTC. Time range shall be less than six months. You must provide either from & to date range or updated date range. updatedFrom default to current time if not provided.
tags:
- "Activity"
parameters:
- name: 'fromDate'
in: query
description: Filter activities happened after this date. UTC time. Shall be date before `toDate`.
required: false
schema:
type: string
format: "date-time"
example: '2021-10-01 00:00:00'
- name: 'toDate'
in: query
description: Filter activities happened until this date. UTC time. Cannot be future date.
required: false
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'updatedFrom'
in: query
description: Filter activities updated after this date. UTC time. Shall be date before `updatedTo`.
required: false
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'updatedTo'
in: query
description: Filter activities updated until this date. UTC time. Cannot be future date. Default value equals to current time.
required: false
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'status'
in: query
description: in-progress - for activity type “softphone", "softphone-inbound" and "conference”. These are meetings or calls that are being processed.
completed - for activity type “softphone", "softphone-inbound" and "conference”. These are meetings or calls that have been processed.
received - for activity type "sms-inbound" and "sms-outbound”. This is only for Jiminny Voice dialer.
sent - for activity type "sms-inbound" and "sms-outbound”. This is only for Jiminny Voice dialer.
delivered - for activity type "sms-inbound" and "sms-outbound”. This is only for Jiminny Voice dialer.
required: false
schema:
type: string
enum: [ 'received', 'sent', 'delivered', 'in-progress', 'completed' ]
- name: 'page'
in: query
description: Page number to return. Default value 1. Page size is controlled by the
pageSize parameter (default 500).
required: false
schema:
type: integer
minimum: 1
example: 1
- name: 'pageSize'
in: query
description: Number of activities per page. Lowering it is the recommended way to
make this heavy endpoint respond faster.
required: false
schema:
type: integer
minimum: 1
maximum: 500
default: 500
- name: 'accountId'
in: query
description: Filter activities by CRM account. Value is the external CRM
provider ID of the account (e.g. the Salesforce or HubSpot account ID), scoped
to your organization. Unknown IDs return no activities.
required: false
schema:
type: string
maxLength: 255
- name: 'opportunityId'
in: query
description: Filter activities by CRM opportunity / deal. Value is the external
CRM provider ID of the opportunity, scoped to your organization. Unknown IDs
return no activities.
required: false
schema:
type: string
maxLength: 255
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'400':
description: 'Input parameters error'
content:
'application/json':
schema:
$ref: '#/components/schemas/EnvelopeError'
example: {"errors": {"range": "From date shall be less than to date."}}
'200':
description: 'List of activities and metadata'
content:
'application/json':
schema:
type: object
properties:
results:
type: array
items:
allOf:
- $ref: '#/components/schemas/Activity'
metadata:
type: "object"
properties:
page:
type: number
description: 'The current page number. 0 (with maxPage 0) when there are no results.'
minimum: 0
maximum: 10000
example: 1
pageSize:
type: "integer"
description: 'The requested page size — default and max 500 (settable via the pageSize parameter on /getActivities only). Does NOT shrink on the last page; count results instead.'
example: 500
maxPage:
type: "integer"
example: 1
description: 'Calculated maximum page for the current filters. If query `page` > maxPage it would be considered `page=maxPage`'
nextPage:
type: 'string'
example: ''
description: 'The URL to access the next page. Present if calculated next page. When current request is for the last request it is not present.'
failed:
type: array
items:
type: string
description: 'Activities members of current page for which the data building failed. Contact support for additional information.'
example: ["1cbbb13b-cf63-487a-8ab5-e5070c6cc21a", "ee5b9b5a-1a6f-418c-9d61-803e34e7bc7a"]
/getActionItems:
get:
description: Get action items for a given activity.
tags:
- "ActionItem"
parameters:
- name: 'activityId'
in: query
description: The activity uuid you wish to retrieve the action items for.
required: true
schema:
type: string
format: "uuid"
example: "7efa9c4f-9c47-4922-9ae7-e61a3dbecd72"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: 'Input validation failed — including an activityId that is not a known, valid
activity id'
content:
'application/json':
schema:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
properties:
activityId:
type: array
items:
type: string
example: "The selected activity id is invalid."
'404':
description: 'The activity is not available to your organization, or its action items are not
generated yet.'
content:
'application/json':
schema:
type: object
properties:
error:
type: string
example: 'Action items are being generated. Please check again shortly.'
'204':
description: 'There are no action items available and none are coming. No response
body.'
'200':
description: 'List of action items.'
content:
'application/json':
schema:
type: object
properties:
actionItems:
type: object
properties:
content:
type: array
items:
type: string
description: 'List of action items'
/getQuestions:
get:
description: Gets questions based on activityId.
tags:
- "Questions"
parameters:
- name: 'activityId'
in: query
required: true
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: 'Input parameters error'
content:
'application/json':
schema:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
properties:
activityId:
type: array
items:
type: string
example: "The selected activity id is invalid."
'404':
description: 'The activity is not available to your organization.'
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: array
items:
type: object
properties:
startsAt:
type: number
example: 84.39
endsAt:
type: number
example: 88.77
participantId:
type: string
example: b5b80942-b922-4f84-b390-5c958e736387
text:
type: string
example: "Should we offer the same?"
isEngaging:
type: boolean
example: false
isInsightful:
type: boolean
example: false
/listens:
get:
description: Gets listened activities data.
tags:
- "Play"
parameters:
- name: 'fromDate'
in: query
description: Filter listened activities data happened after this date. UTC time. Shall be date before `toDate`.
required: true
schema:
type: string
format: "date-time"
example: '2021-10-01 00:00:00'
- name: 'toDate'
in: query
description: Filter listened activities data happened until this date. UTC time. Cannot be future date.
required: true
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'userId'
in: query
required: false
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
- name: 'page'
in: query
required: false
description: Page number to return. Default value 1.
schema:
type: integer
minimum: 1
maximum: 10000
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'400':
description: 'Filter/scope validation failed ({errors} body).'
content:
'application/json':
schema:
$ref: '#/components/schemas/EnvelopeError'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: object
properties:
results:
type: array
items:
allOf:
- $ref: '#/components/schemas/Play'
metadata:
type: "object"
properties:
page:
type: number
description: 'The current page number. 0 (with maxPage 0) when there are no results.'
minimum: 0
maximum: 10000
example: 1
pageSize:
type: "integer"
description: 'The requested page size — default and max 500 (settable via the pageSize parameter on /getActivities only). Does NOT shrink on the last page; count results instead.'
example: 500
maxPage:
type: "integer"
example: 1
description: 'Calculated maximum page for the current filters. If query `page` > maxPage it would be considered `page=maxPage`'
nextPage:
type: 'string'
example: ''
description: 'The URL to access the next page. Present if calculated next page. When current request is for the last request it is not present.'
failed:
type: array
items:
type: string
description: 'Always empty for this endpoint — only /getActivities
reports per-record failures.'
example: []
/automated-call-scoring:
get:
description: Gets automated call scoring data.
tags:
- "Automated call scoring"
parameters:
- name: 'userId'
in: query
required: false
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
- name: 'fromDate'
in: query
required: false
description: Return scores from this date. UTC; date or date-time. Required
whenever toDate is sent (the dates come as a pair).
schema:
type: string
format: "date-time"
example: '2021-10-01 00:00:00'
- name: 'toDate'
in: query
required: false
description: Return scores until this date. UTC; date or date-time. Required
whenever fromDate is sent.
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'page'
in: query
required: false
description: Page number to return. Default value 1.
schema:
type: integer
minimum: 1
maximum: 10000
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'400':
description: 'Unknown or invalid userId ({errors} body — the response-envelope error).'
content:
'application/json':
schema:
$ref: '#/components/schemas/EnvelopeError'
'422':
description: 'Field validation failed (dates, page — Laravel {message, errors} body).
Branch on 400 for a bad userId, 422 for malformed fields.'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: object
properties:
results:
type: array
items:
allOf:
- $ref: '#/components/schemas/AutomatedCallScoring'
metadata:
type: "object"
properties:
page:
type: number
description: 'The current page number.'
minimum: 1
maximum: 10000
example: 1
pageSize:
type: "integer"
description: 'Rows in the current `results` array — equals count(results), so smaller on the last page.'
example: 500
maxPage:
type: "integer"
example: 1
description: 'Calculated maximum page for the current filters. A `page` beyond maxPage is clamped — the response reports `page = maxPage` but with an EMPTY results array, not the last page''s rows.'
failed:
type: array
items:
type: string
description: 'Always empty for this endpoint — only /getActivities
reports per-record failures.'
example: []
/comments:
get:
description: Gets comment data.
tags:
- "Comments"
parameters:
- name: 'userId'
in: query
required: false
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
- name: 'fromDate'
in: query
description: Filter comments data happened after this date. UTC time. Shall be date
before `toDate`, at most 5 months before it, and is required whenever `toDate` is
sent (the dates come as a pair).
required: false
schema:
type: string
format: "date-time"
example: '2021-10-01 00:00:00'
- name: 'toDate'
in: query
description: Filter comments data happened until this date. UTC time. Cannot be
future date. Required whenever `fromDate` is sent.
required: false
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'page'
in: query
required: false
description: Page number to return. Default value 1.
schema:
type: integer
minimum: 1
maximum: 10000
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: 'Input validation failed — bad userId/page/date formats, or the date
checks: fromDate must be before toDate, the range at most 5 months, toDate not in
the future.'
content:
'application/json':
schema:
type: object
properties:
message:
type: string
example: "The given data was invalid."
errors:
type: object
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: object
properties:
results:
type: array
items:
allOf:
- $ref: '#/components/schemas/ActivityComment'
metadata:
type: "object"
properties:
page:
type: number
description: 'The current page number.'
minimum: 1
maximum: 10000
example: 1
pageSize:
type: "integer"
description: 'Rows in the current `results` array — equals count(results), so smaller on the last page.'
example: 500
maxPage:
type: "integer"
example: 1
description: 'Calculated maximum page for the current filters. Unlike the other paginated endpoints, the requested `page` is NOT clamped to it — a `page` beyond maxPage is echoed back with an empty `results`'
failed:
type: array
items:
type: string
description: 'Always empty for this endpoint — only /getActivities
reports per-record failures.'
example: []
/coaching-feedback:
get:
description: Gets coaching feedback bulk data.
tags:
- "Coaching Feedback"
parameters:
- name: 'fromDate'
in: query
description: Filter coaching feedback bulk data after this date. UTC time. Shall be date before `toDate`.
required: true
schema:
type: string
format: "date-time"
example: '2021-10-01 00:00:00'
- name: 'toDate'
in: query
description: Filter coaching feedback bulk data until this date. UTC time. Cannot be future date.
required: true
schema:
type: string
format: "date-time"
example: '2021-11-01 00:00:00'
- name: 'coachId'
in: query
required: false
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
- name: 'coacheeId'
in: query
required: false
schema:
type: string
format: "uuid"
example: "8f3aaa1a-1676-434e-9783-c3c3fa7ff3a0"
- name: 'page'
in: query
required: false
description: Page number to return. Default value 1.
schema:
type: integer
minimum: 1
maximum: 10000
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'400':
description: 'Filter/scope validation failed ({errors} body).'
content:
'application/json':
schema:
$ref: '#/components/schemas/EnvelopeError'
'403':
description: 'Request not authenticated. Check token'
content:
'application/json':
schema:
type: array
items:
type: string
example: ["Not allowed"]
'200':
description: 'Successful operation.'
content:
'application/json':
schema:
type: object
properties:
results:
type: array
items:
allOf:
- $ref: '#/components/schemas/CoachingFeedbackBulk'
metadata:
type: "object"
properties:
page:
type: number
description: 'The current page number. 0 (with maxPage 0) when there are no results.'
minimum: 0
maximum: 10000
example: 1
pageSize:
type: "integer"
description: 'The requested page size — default and max 500 (settable via the pageSize parameter on /getActivities only). Does NOT shrink on the last page; count results instead.'
example: 500
maxPage:
type: "integer"
example: 1
description: 'Calculated maximum page for the current filters. If query `page` > maxPage it would be considered `page=maxPage`'
nextPage:
type: 'string'
example: ''
description: 'The URL to access the next page. Present if calculated next page. When current request is for the last request it is not present.'
failed:
type: array
items:
type: string
description: 'Always empty for this endpoint — only /getActivities
reports per-record failures.'
example: []
/uploadActivity:
post:
summary: Upload an activity
description: Upload an activity with a file and additional metadata. Returns the activityId on successful upload.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: "#/components/schemas/UploadActivityRequest"
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'201':
description: Activity successfully uploaded.
content:
application/json:
schema:
type: object
properties:
activityId:
type: string
format: uuid
description: The UUIDv4 of the uploaded activity.
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: Input validation failed (including reuse of an externalId already known
for the host — unlike the Zapier variant, reuse here is rejected, not idempotent).
'500':
description: Internal Server Error.
tags:
- Activity
/getActivity:
get:
summary: Return a single activity by ID
description: Same representation as one item of /getActivities (fixed include set — tracks, comments, coaching feedback, notes, participants, stats, topic triggers, CRM data).
parameters:
- in: query
name: activityId
required: true
schema:
type: string
format: uuid
description: The UUIDv4 of the activity.
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: The activity.
content:
application/json:
schema:
$ref: '#/components/schemas/Activity'
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'404':
description: The activity is not available to your organization.
'422':
description: Input validation failed — including an activityId that does not exist
(existence is part of validation, so an unknown id is a 422, not a 404).
'500':
description: The activity could not be transformed for output.
tags:
- Activity
/zapier/uploadActivity:
post:
summary: Upload an activity by recording URL (Zapier variant)
description: Unlike /uploadActivity this takes no file — the recording is fetched from a
publicly reachable recordingUrl. Full analysis is always skipped for this variant.
Idempotent on externalId — re-sending the same externalId for the same host returns the
existing activityId with HTTP 200 (whereas /uploadActivity rejects externalId reuse
with a 422).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- recordingUrl
- hostUserEmail
- language
- title
properties:
recordingUrl:
type: string
format: uri
description: Publicly reachable URL of the recording to import. Must resolve
(active_url) and must not point at a private address.
hostUserEmail:
type: string
format: email
description: The email of the host user. Must belong to your team.
language:
type: string
description: The language locale of the activity e.g. en_GB. Hyphenated,
mixed-case and bare language codes (e.g. EN-us, en) are normalized.
title:
type: string
maxLength: 250
description: The title of the activity.
completedAt:
type: string
format: date-time
description: The date the activity was completed.
opportunityId:
type: string
maxLength: 100
description: An optional CRM Opportunity ID associated with the activity.
accountId:
type: string
maxLength: 100
description: An optional CRM Account ID associated with the activity.
leadId:
type: string
maxLength: 180
description: An optional CRM Lead ID associated with the activity.
externalId:
type: string
maxLength: 191
description: Caller-side identifier used for idempotent re-delivery.
notifyForUploadCompletionByEmail:
type: boolean
description: Whether to notify the host via email when the upload is complete.
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: An activity already exists for this externalId and host. Returns the existing activityId; nothing is created.
content:
application/json:
schema:
type: object
properties:
activityId:
type: string
format: uuid
'201':
description: Uploaded. Returns activityId.
content:
application/json:
schema:
type: object
properties:
activityId:
type: string
format: uuid
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'409':
description: Duplicate upload (same recordingUrl for the same host). Returns the
existing activityId and a message. Note that for both the 200 and 409 duplicate
responses, the referenced activity may since have been deleted and no longer be
retrievable via the API.
content:
application/json:
schema:
type: object
properties:
activityId:
type: string
format: uuid
message:
type: string
'422':
description: Input validation failed.
'500':
description: Internal Server Error.
tags:
- Activity
/getAiScorecard:
get:
summary: Return the AI scorecards for one activity
parameters:
- in: query
name: activityId
required: true
schema:
type: string
format: uuid
description: The UUID of the activity to retrieve scorecard results for.
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Activity summary plus its AI scorecard runs.
content:
application/json:
schema:
$ref: '#/components/schemas/AiScorecardResult'
'204':
description: The activity has no AI scorecard runs.
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'404':
description: The activity is not available to your organization.
'422':
description: Input validation failed — including an activityId that does not exist
(existence is part of validation, so an unknown id is a 422, not a 404).
tags:
- AI Scoring
/getAiScorecards:
get:
summary: List AI scorecards for a date range (paginated)
description: Filtered by the date the scoring was completed (`created_at`), not the
call date. `fromDate` and `toDate` are both required.
parameters:
- in: query
name: fromDate
required: true
schema:
type: string
description: Return scorecards completed on or after this date. UTC. Accepts a date
or a date-time (e.g. 2026-08-01 or 2026-08-01 00:00:00). Must be before toDate.
- in: query
name: toDate
required: true
schema:
type: string
description: Must be on or after fromDate. Accepts a date or a date-time. UTC.
- in: query
name: page
description: Page number to return. Default value 1.
schema:
type: integer
minimum: 1
maximum: 10000
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Paginated results envelope; each result carries an activity summary and
its scorecards. No nextPage is emitted — iterate page until maxPage.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/AiScorecardResult'
metadata:
type: object
properties:
page:
type: integer
example: 1
pageSize:
type: integer
description: Rows in the current results array (500 max).
example: 500
maxPage:
type: integer
example: 3
failed:
type: array
items:
type: string
description: Always empty for this endpoint.
example: []
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: Input validation failed.
tags:
- AI Scoring
/automated-reports:
get:
summary: List AI (automated) reports shared with at least one team (paginated, 100/page)
description: Only reports shared with at least one TEAM are exposed — reports shared
solely with individual team members, or not shared at all, are never returned. Each
item includes the latest generation result.
parameters:
- in: query
name: page
description: Page number to return. Page size is 100 reports. Default value 1.
schema:
type: integer
minimum: 1
maximum: 10000
- in: query
name: reportType
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter by report type. Repeatable to include multiple types.
- in: query
name: frequency
schema:
type: string
enum: [daily, weekly, twice_monthly, monthly, quarterly, one_off]
description: Not validated server-side — an unknown value returns an empty result set, not a 422.
- in: query
name: fromDate
schema:
type: string
description: Only return reports created on or after this date. UTC. Accepts a date
or a date-time.
- in: query
name: toDate
schema:
type: string
description: Must be on or after fromDate. Accepts a date or a date-time. UTC.
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Paginated results envelope of reports; each item includes the latest
generation result.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/AutomatedReport'
metadata:
type: object
properties:
page:
type: number
example: 1
pageSize:
type: number
description: Rows in the current results array (100 max).
example: 100
maxPage:
type: number
example: 3
failed:
type: array
items:
type: string
description: Always empty for this endpoint.
example: []
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'422':
description: Input validation failed.
tags:
- Automated Reports
/automated-reports/{uuid}:
get:
summary: Return a single AI report with its latest result
description: Returns 404 for reports outside your organization, soft-deleted reports,
or reports not shared with any team.
parameters:
- in: path
name: uuid
required: true
description: UUID of the report.
schema:
type: string
format: uuid
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: The report, including its latest generation result.
content:
application/json:
schema:
$ref: '#/components/schemas/AutomatedReport'
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'404':
description: Report not found, not visible to the API (not shared with a team), or malformed UUID.
tags:
- Automated Reports
/automated-reports/{uuid}/status:
get:
summary: Return the generation status of a report's latest result (poll endpoint)
parameters:
- in: path
name: uuid
required: true
description: UUID of the report.
schema:
type: string
format: uuid
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Status of the latest generation run.
content:
application/json:
schema:
type: object
properties:
reportId:
type: string
format: uuid
status:
type: string
enum: [pending, requested, generated, sent, failed]
description: pending also covers a report with no generation run yet.
generatedAt:
type: string
format: date-time
nullable: true
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'404':
description: Report not found or not visible to the API.
tags:
- Automated Reports
/automated-reports/{uuid}/download:
get:
summary: Return a presigned download URL (valid 15 minutes) for a generated report
description: Returns a short-lived presigned URL for the requested artifact of the
report's latest result. The URL expires after 15 minutes.
parameters:
- in: path
name: uuid
required: true
description: UUID of the report.
schema:
type: string
format: uuid
- in: query
name: format
schema:
type: string
enum: [pdf, audio]
default: pdf
description: audio returns the podcast variant when one was generated.
responses:
'401':
$ref: '#/components/responses/Unauthenticated'
'429':
$ref: '#/components/responses/TooManyRequests'
'200':
description: Presigned URL for the artifact.
content:
application/json:
schema:
type: object
properties:
reportId:
type: string
format: uuid
format:
type: string
enum: [pdf, audio]
url:
type: string
format: uri
description: Presigned S3 URL — download promptly.
expiresAt:
type: string
format: date-time
'400':
description: Invalid format value (not a 422).
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeError'
example: {"errors": {"format": "format must be one of: pdf, audio"}}
'403':
description: Request not authenticated.
content:
application/json:
schema:
type: array
items:
type: string
example: ["Not allowed"]
'404':
description: Report/artifact not found, not generated yet, or not visible to the API.
tags:
- Automated Reports
security:
- bearerAuth: []
- apiKeyQuery: []
components:
responses:
Unauthenticated:
description: The token passed the cached middleware map but no longer matches a team
(e.g. it was rotated moments ago). Retry with the current token.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
example: "Unauthenticated."
TooManyRequests:
description: Rate limit exceeded — 120 requests/min per organization (30/min for
/getActivities). Back off and retry after a minute.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "Too Many Attempts."
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Opaque team-level API token (80 random characters, not a JWT), issued once
from the Jiminny app. Also accepted as a POST body field api_token.
apiKeyQuery:
type: apiKey
in: query
name: api_token
description: The same team-level API token passed as a query parameter.
schemas:
EnvelopeError:
type: object
properties:
errors:
type: object
additionalProperties: true
description: Map of field/reason to message.
description: The 400 error body used by the results-envelope endpoints.
UploadActivityRequest:
type: object
required:
- file
- hostUserEmail
- language
- title
properties:
file:
type: string
format: binary
description: The file to upload, max 2 GB. Allowed types are video/x-matroska,
audio/mp4, video/mp4, audio/mpeg, audio/x-wav, audio/x-ms-wma, audio/wma, mp3, mp4,
mkv, wav.
hostUserEmail:
type: string
format: email
description: The email of the host user. Must belong to your team.
language:
type: string
description: The language locale of the activity e.g. en_GB.
notifyForUploadCompletionByEmail:
type: boolean
description: Whether to notify the host via email when the upload is complete.
skipFullAnalysis:
type: boolean
default: true
description: Whether to skip the full analysis of the uploaded activity.
Defaults to true — omit it and analysis is skipped; send false to run full analysis.
title:
type: string
maxLength: 250
description: The title of the activity.
completedAt:
type: string
format: date-time
description: The date the activity was completed.
opportunityId:
type: string
maxLength: 100
description: An optional CRM Opportunity ID associated with the activity.
accountId:
type: string
maxLength: 100
description: An optional CRM Account ID associated with the activity.
leadId:
type: string
maxLength: 180
description: An optional CRM Lead ID associated with the activity.
externalId:
type: string
maxLength: 191
description: An optional external ID. Must be unique to the host.
WebhookTrigger:
type: string
enum:
- ai_scorecard_completed
- coaching_feedback_completed
- conversation_shared
- conversation_exported
- conversation_processed
- conversation_played
- crm_tasks_created
Account:
type: "object"
properties:
id:
type: string
format: uuid
example: "7efa9c4f-9c47-4922-9ae7-e61a3dbecd72"
crmId:
type: string
example: "00146000003mf8JAAQ"
photoUrl:
type: string
format: url
example: "https://media.app.jiminny.com/92c8faa0-b574-48b4-9376-78fb7bba3ea2/avatars/00146000003mf8JAAQ.png"
name:
type: string
example: "Spotify"
phone:
type: string
format: phone
example: "+447915056215"
formattedPhone:
type: string
format: phone
example: "07915 056215"
countryCode:
type: string
example: "US"
type:
type: string
example: "account"
crmUrl:
type: string
format: url
example: "https://jmny-dev-ed.my.salesforce.com/00146000003mf8JAAQ"
Opportunity:
type: "object"
properties:
id:
type: string
format: uuid
example: "7efa9c4f-9c47-4922-9ae7-e61a3dbecd72"
crmId:
type: string
example: "00146000003mf8JAAQ"
value:
type: number
format: float
example: 150000.00
name:
type: string
example: "SaaS Renewal 2024"
currency:
type: string
example: "USD"
formattedCurrency:
type: string
example: "$150,000.00"
won:
type: boolean
closed:
type: boolean
example: false
closeDate:
type: string
format: date
stageUpdatedAt:
type: string
format: date-time
Organization:
type: "object"
description: The payload is Jiminny's internal team representation (shared with the web
app), so alongside the stable fields below it carries a tail of team-settings fields
(calendarProvider, currencyCode, language, timezone, countryCode, botName, recording
and compliance preferences, slackBotEnabled, createdAt, ownerId, …) that may change
between releases.
required:
- id
- name
additionalProperties: true
properties:
id:
type: string
format: uuid
name:
type: "string"
example: "Dunder Mifflin"
photoUrl:
type: "string"
nullable: true
transparentPhotoUrl:
type: "string"
nullable: true
hasApiKey:
type: "boolean"
example: true
calendarProvider:
type: "string"
nullable: true
example: "google"
currencyCode:
type: "string"
nullable: true
example: "USD"
timezone:
type: "string"
nullable: true
example: "America/New_York"
createdAt:
type: "string"
format: date-time
nullable: true
ownerId:
type: "string"
format: uuid
nullable: true
Stage:
type: "object"
properties:
id:
type: "string"
format: "uuid"
example: "60798540-f60c-4a9c-938e-4b1d07c6f393"
label:
type: "string"
name:
type: "string"
type:
type: "string"
format: "enum"
enum:
- "opportunity"
- "lead"
- "all"
Tracks:
type: array
items:
$ref: "#/components/schemas/Track"
Track:
type: object
required:
- id
- type
- format
- size
- resolution
- startTime
- endTime
- duration
- file
properties:
id:
type: string
description: 'Unique identifier of media asset'
format: uuid
type:
type: string
description: 'Audio or video asset type'
example: 'video'
enum: ['audio', 'video']
format:
type: string
example: 'mkv'
enum: ['m4a','mkv']
description: 'M4a for audio and mkv for video assets. Video assets contains audio'
size:
type: number
example: 113611448
description: 'Asset size on disk in bytes'
resolution:
type: number
description: 'non-nullable only for video assets.'
enum: [240,480,720]
example: 720
nullable: true
startTime:
type: string
format: date-time
description: 'Start moment for current asset'
endTime:
type: string
format: date-time
description: 'End time for current asset'
duration:
type: number
format: float
example: 829.42
description: 'Duration for current asset'
file:
type: object
required:
- downloadUrl
- urlValidUntil
properties:
downloadUrl:
type: string
format: url
example: 'https://example.com/file.mp3'
description: 'AWS S3 signed url for the current asset media file for download'
urlValidUntil:
type: string
format: date-time
description: 'Point in future where `downloadUrl` will expire. Default expire = 24 hours'
Comments:
type: array
items:
$ref: "#/components/schemas/Comment"
Comment:
type: object
properties:
id:
type: string
format: uuid
createdAt:
type: string
format: date-time
message:
type: string
example: 'Good job!'
startTime:
type: number
format: float
example: 0
user:
$ref: "#/components/schemas/User"
endTime:
type: number
format: float
example: 0
children:
type: array
items:
type: object
example: {"id": "550e8400-e29b-41d4-a716-446655440000", "body": "Child comment text"}
User:
type: object
properties:
id:
type: string
format: uuid
description: 'Unique identifier for user team member'
name:
type: string
description: 'Full name of user team member'
example: 'James Graham'
email:
type: string
format: email
description: 'Full email address of user team member. Source for calendar events'
example: 'james.graham@jiminny.com'
title:
type: string
description: 'Job title of the user'
example: 'Sales Rep'
teamName:
type: string
description: 'Team name of the user'
example: 'US Mid Market'
CoachingFeedback:
type: array
items:
$ref: "#/components/schemas/SingleFeedback"
SingleFeedback:
type: object
required:
- id
- frameworkName
- averageScore
- createdAt
- updatedAt
- sectionFeedbacks
- coach
- coachee
properties:
id:
type: string
description: 'Unique identifier for `coach` member of the team doing a coaching feedback with framework `frameworkName` towards `coachee` member of the team'
format: uuid
frameworkName:
type: string
description: 'Activity type (e.g. Coaching framework) when feedback was given'
averageScore:
type: number
format: float
description: 'Average score for all section feedback members of this coaching feedback for current activity'
example: 3.33
createdAt:
type: string
description: 'When first the feedback was created'
format: date-time
updatedAt:
type: string
format: date-time
description: 'Last time the coaching feedback was updated for example add more section feedback'
sectionFeedbacks:
type: array
items:
$ref: "#/components/schemas/SectionFeedback"
coach:
$ref: "#/components/schemas/User"
coachee:
$ref: "#/components/schemas/User"
SectionFeedback:
type: object
required:
- id
properties:
id:
type: string
format: uuid
sectionDefinition:
type: string
description: 'Section definition for the Framework'
score:
type: number
minimum: 1
maximum: 5
description: 'Given score for current section. Used for average coaching feedback calculation and further for average score for activity.'
summary:
type: string
description: 'Summary text from coach to coachee about this section'
createdAt:
type: string
format: date-time
description: 'Date when first time section feedback was created for current activity from current coach for current coachee'
updatedAt:
type: string
format: date-time
description: 'Date when section feedback was last updated. If not updated in time equals to `createdAt`'
sectionCriteriaFeedback:
type: array
items:
$ref: "#/components/schemas/SectionCriteriaFeedback"
SectionCriteriaFeedback:
type: object
description: 'Each section can have multiple criteria'
properties:
id:
type: string
format: uuid
content:
type: string
description: 'Text note for current criterion, unique to every section definition'
createdAt:
type: string
format: date-time
description: 'Date when first time criterion feedback was created for current activity from current coach for current coachee'
updatedAt:
type: string
format: date-time
description: 'Date when criterion feedback was last updated. If not updated in time equals to `createdAt`'
criterionDefinition:
type: object
required:
- id
- name
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: 'Unique identifier of section definition criterion child member'
name:
type: string
description: 'Definition of given section criterion member'
createdAt:
type: string
format: date-time
description: 'Date when first time criterion was created for given section'
updatedAt:
type: string
format: date-time
description: 'Date when first time criterion was created for given section. If not updated in time equals to `createdAt`'
Notes:
type: object
properties:
summary:
type: string
description: 'Summary added to CRM for current activity'
nullable: true
coaching:
type: array
items:
$ref: "#/components/schemas/Message"
meeting:
type: array
items:
$ref: "#/components/schemas/Message"
Message:
type: object
properties:
message:
type: string
description: 'Text body of the message'
isPrivate:
type: boolean
description: 'Is this message private or public'
time:
type: number
format: float
description: 'When the message was created relatively to activity start and duration'
timeForHumans:
type: string
description: 'Calculated, more human readable value based on `time`'
Participant:
type: object
required:
- name
- id
properties:
id:
type: string
format: uuid
transcriptionId:
type: number
description: 'Numeric identifier used for transcription and `caller` `callee`'
providerId:
type: string
nullable: true
description: 'CRM provider identifier of participant'
name:
type: string
example: "James Graham"
phone:
type: string
email:
type: string
enterTime:
type: string
description: 'Absolute time when participant joined activity'
format: date-time
exitTime:
type: string
description: 'Absolute time when participant left activity'
format: date-time
user:
$ref: "#/components/schemas/User"
contact:
type: object
nullable: true
properties:
id:
type: string
format: uuid
crmId:
type: string
nullable: true
example: '0034p00001moXo9AAE'
title:
type: string
description: 'CRM contact description'
email:
type: string
description: 'CRM contact email address'
phone:
type: string
mobile:
type: string
countryCode:
type: string
nullable: true
lead:
type: object
properties:
id:
type: string
format: uuid
description: 'Unique identifier of CRM lead imported for team'
crmId:
type: string
description: 'CRM unique lead identifier'
name:
type: string
company:
type: string
description: 'CRM company for lead'
title:
type: string
description: 'CRM source data'
email:
type: string
description: 'CRM imported email for lead'
formattedPhone:
type: string
description: 'CRM formatted phone number for lead'
formattedMobile:
type: string
description: 'CRM formatted mobilephone number for lead'
countryCode:
type: string
nullable: true
description: 'CRM lead country code'
stageUpdatedAt:
type: string
format: date-time
crmUrl:
type: string
description: 'CRM url for lead object'
stage:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
description: 'CRM stage name'
label:
type: string
description: 'CRM label for stage'
type:
type: string
description: 'CRM type'
sequence:
type: number
example: 0
description: 'CRM sequence'
probability:
type: string
isOrganizer:
type: boolean
description: 'True if participant is activity owner'
durationForHumans:
type: string
example: "12m 24s"
Participants:
type: array
items:
$ref: "#/components/schemas/Participant"
TopicTrigger:
type: object
required:
- name
properties:
theme:
type: string
description: 'Theme definition'
example: "Agenda & Scheduling"
topic:
type: string
description: 'Topic definition'
example: "Discussed Scheduling"
word:
type: string
example: 'calendar'
description: 'The word trigger in transcription'
count:
type: number
example: 1
description: 'The amount of times transcribed activity speech triggers current `theme` and `topic`'
TopicTriggers:
type: array
items:
$ref: "#/components/schemas/TopicTrigger"
ActivityStats:
type: object
description: 'Not present for `sms-inbound` and `sms-outbound` activity types'
properties:
favorites:
type: integer
description: 'The number of times this activity got added to default playlist'
example: 1
plays:
type: integer
description: 'The number of times this activity got played on playback page'
example: 1
comments:
type: integer
description: 'The number of comments from team members this activity has'
example: 14
shares:
type: integer
description: 'The number of times this activity was shared with team members via Slack for example.'
example: 2
duration:
type: number
format: float
description: 'Duration in seconds for the current activity'
example: 800
talkDuration:
type: number
description: 'Calculated amount of time all speakers were talking during activity.'
format: float
customerTalkDuration:
type: number
description: 'Calculated amount of time customer was talking during activity'
format: float
longestUserMonologue:
type: number
description: 'Calculated longest uninterrupted activity owner speech during activity'
format: float
longestCustomerMonologue:
type: number
description: 'Calculated longest uninterrupted customer speech during activity'
format: float
interactions:
type: integer
example: 3
patienceTime:
type: number
format: float
talkingSpeed:
type: number
format: float
talkTimeRatio:
type: number
format: float
conversationSwitch:
type: number
format: float
userQuestionsCount:
type: integer
customerQuestionsCount:
type: integer
engagingQuestionsCount:
type: integer
insightfulQuestionsCount:
type: integer
participantStats:
type: object
properties:
talkTimeRatio:
type: object
description: 'key Participant Uuid and value is the percentage of time each participant was talking upto 100%'
example:
"4e070141-1e5e-4285-8e63-b534cad648ae": 3
"9147af86-e1ca-456b-a270-eb3e2fb55021": 97
TranscriptSegment:
type: object
description: 'Segment of the transcription'
properties:
startsAt:
type: number
format: float
description: 'Seconds into the conversation when the segment started'
endsAt:
type: number
format: float
description: 'Seconds into the conversation when the segment ended'
transcript:
type: string
example: "Upon the sides of this square post, I cut every a notch with my knife. And every seventh notch was as long again as the rest."
participantId:
type: string
format: uuid
nullable: true
description: 'The participant who spoke (null when the speaker could not be mapped)'
example: 'c235c636-37aa-49a9-8f20-a59f1e739e7c'
username:
type: string
nullable: true
description: 'Display name of the speaker (null when unknown)'
Activity:
type: object
description: 'Single activity'
required:
- id
- type
- status
properties:
id:
type: string
format: uuid
description: 'Unique indentifier of current activity.'
type:
type: string
enum: ["softphone", "softphone-inbound", "conference", "sms-inbound", "sms-outbound"]
example: "conference"
description: 'Type of the current activity. Schema depends on it.'
activityType:
type: string
description: 'User set activity type'
example: 'Web Demo'
externalProviderId:
type: string
nullable: true
description: 'Conference or call center external record id'
providerDisplayName:
type: string
example: "Zoom"
description: 'Name of the integration current activity is created for.'
title:
type: string
example: "Catchup call with Procurement"
value:
type: number
format: float
nullable: true
formattedValue:
type: string
nullable: true
description: 'Human readable currency-formatted cost for the connected opportunity'
example: "$5,450"
duration:
type: integer
description: 'Activity duration in seconds'
example: 830
durationForHumans:
type: string
description: 'Human readable amount of time representing the duration of the activity. Calculated value from `duration`'
example: "13m 50s"
createdAt:
type: string
description: 'For activity type `softphone` and `softphone-inbound`. The time activity got created. Usually close to actual moment in time the activity happened.'
format: "date-time"
sentAt:
type: string
description: 'For activity type `sms-outbound` - the time when the sms being sent.'
format: "date-time"
receivedAt:
type: string
description: 'For activity type `sms-inbound` - the time when the sms being received.'
format: "date-time"
actualEndTimeForHumans:
type: string
description: 'Calculated value - human readable end time. Only for activity type `conference`.'
scheduledStartTime:
type: string
description: 'Calendar imported activity/meeting type `conference`. This is the time that the event, for which this activity is, was scheduled to start. For activity type `conference`'
format: "date-time"
scheduledEndTime:
type: string
description: 'Calendar imported activity/meeting type `conference`. This is the time that the event, for which this activity is, was scheduled to end.'
format: "date-time"
actualStartTime:
type: string
description: 'The actual time the activity has started. Can differ from `scheduledStartTime`'
format: "date-time"
actualEndTime:
type: string
description: 'The actual time the activity ended. Can differ from `scheduledEndTime`'
format: "date-time"
updatedAt:
type: string
description: 'Last update for this activity'
format: "date-time"
status:
type: string
enum: [ 'received', 'sent', 'delivered', 'in-progress', 'completed' ]
description: |
`in-progress` - for activity type "softphone", "softphone-inbound" and "conference". These are meetings or calls that are being processed
`completed` - for activity type "softphone", "softphone-inbound" and "conference". These are meetings or calls that have been processed
`received` - for activity type "sms-inbound" and "sms-outbound". This is only for Jiminny Voice dialer
`sent` - for activity type "sms-inbound" and "sms-outbound". This is only for Jiminny Voice dialer
`delivered` - for activity type "sms-inbound" and "sms-outbound". This is only for Jiminny Voice dialer
example: "completed"
averageScore:
type: number
description: 'Average all score coaching feedback. You can have 2 feedback having one average score 2 and second one 5 for current activity - the average score for the activity would be 3.5 in this case'
nullable: true
example: 3.5
participantCount:
type: number
description: 'Number of participants for this activity. For softphone usually two, for conferences can be 50 participants on the meeting'
example: 0
fromParticipantId:
type: string
format: uuid
description: 'Unique identifier for activity types - `softphone` and `softphone-inbound`. Represents caller'
example: "7efa9c4f-9c47-4922-9ae7-e61a3dbecd72"
toParticipantId:
type: string
format: uuid
description: 'Unique identifier for activity types - `softphone` and `softphone-inbound`. Represents callee'
example: "7efa9c4f-9c47-4922-9ae7-e61a3dbecd72"
stats:
$ref: "#/components/schemas/ActivityStats"
isLogged:
description: 'Represents is the activity logged into CRM'
type: boolean
crmUrl:
description: 'Represent the CRM url for this logged activity'
type: string
nullable: true
account:
$ref: "#/components/schemas/Account"
opportunity:
$ref: "#/components/schemas/Opportunity"
stage:
$ref: "#/components/schemas/Stage"
tracks:
$ref: "#/components/schemas/Tracks"
comments:
$ref: "#/components/schemas/Comments"
organizer:
$ref: "#/components/schemas/User"
notes:
$ref: "#/components/schemas/Notes"
coachingFeedback:
$ref: "#/components/schemas/CoachingFeedback"
participants:
$ref: "#/components/schemas/Participants"
topicTriggers:
$ref: "#/components/schemas/TopicTriggers"
category:
type: object
nullable: true
properties:
id:
type: string
format: uuid
name:
type: string
example: "Web Demo"
Play:
type: object
properties:
activityId:
type: string
description: 'Activity identifier'
example: "4bc771f1-3a6d-4380-afe5-85e391677b15"
userId:
type: string
description: 'User identifier'
example: "91d750af-c882-42f0-a6c3-7c2f2986a6b9"
listenedAt:
type: string
description: 'When the activity was listened at'
format: "date-time"
AutomatedCallScoring:
type: object
properties:
activityId:
type: string
description: 'Activity identifier'
example: "4bc771f1-3a6d-4380-afe5-85e391677b15"
activityType:
type: string
description: 'Category type of the activity'
example: "Web demo"
score:
type: number
description: 'Score'
example: 2.5
date:
type: string
description: 'When the score was given at'
format: "date-time"
example: '2021-10-01 00:00:00'
userId:
type: string
description: 'User identifier'
example: "91d750af-c882-42f0-a6c3-7c2f2986a6b9"
userName:
type: string
description: 'Name of the user'
example: "John Doe"
CoachingFeedbackBulk:
type: object
properties:
id:
type: string
description: 'Coaching Feedback identifier'
example: "4bc771f1-3a6d-4380-afe5-85e391677b15"
activityId:
type: string
description: 'Activity identifier'
example: "4bc771f1-3a6d-4380-afe5-85e391677b15"
coachId:
type: string
description: 'Coach identifier'
example: "91d750af-c882-42f0-a6c3-7c2f2986a6b9"
coacheeId:
type: string
description: 'Coach identifier'
example: "91d750af-c882-42f0-a6c3-7c2f2986a6b9"
averageScore:
type: number
description: 'Average Score'
example: 2.5
createdAt:
type: string
description: 'When the feedback was given at'
format: "date-time"
example: '2021-10-01 00:00:00'
ActivityComment:
type: object
properties:
id:
type: string
description: 'Activity Comment identifier'
example: "4bc771f1-3a6d-4380-afe5-85e391677b15"
activityId:
type: string
description: 'Activity identifier'
example: "4bc771f1-3a6d-4380-afe5-85e391677b15"
userId:
type: string
description: 'User identifier'
example: "91d750af-c882-42f0-a6c3-7c2f2986a6b9"
createdAt:
type: string
description: 'When the comment was given at'
format: "date-time"
example: '2021-10-01 00:00:00'
Webhook:
type: object
properties:
id:
type: string
format: uuid
example: a3f66e54-04b2-4db6-b4e3-60b88e6e4384
url:
type: string
format: uri
example: https://example.com/webhooks
trigger:
$ref: '#/components/schemas/WebhookTrigger'
origin:
type: string
example: customer
externalId:
type: string
nullable: true
example: external-uuid-123
configuration:
type: object
nullable: true
additionalProperties: true
example:
include_transcript: true
createdAt:
type: string
format: date-time
example: '2024-01-15T10:30:00+00:00'
AutomatedReport:
type: object
properties:
id:
type: string
format: uuid
example: a3f66e54-04b2-4db6-b4e3-60b88e6e4384
name:
type: string
nullable: true
example: Weekly Sales Summary
type:
type: string
example: exec_summary
frequency:
type: string
enum:
- daily
- weekly
- twice_monthly
- monthly
- quarterly
- one_off
example: weekly
dateFrom:
type: string
format: date-time
nullable: true
dateTo:
type: string
format: date-time
nullable: true
teamId:
type: string
format: uuid
description: The UUID of the organization that owns the report.
active:
type: boolean
description: Whether the report schedule is enabled.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
latestResult:
nullable: true
allOf:
- $ref: '#/components/schemas/AutomatedReportResult'
AutomatedReportResult:
type: object
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- pending
- requested
- generated
- sent
- failed
example: generated
requestedAt:
type: string
format: date-time
nullable: true
generatedAt:
type: string
format: date-time
nullable: true
sentAt:
type: string
format: date-time
nullable: true
formats:
type: array
description: One entry per available media type for this result.
items:
type: object
properties:
format:
type: string
enum:
- pdf
- audio
available:
type: boolean
description: True when the artifact is generated and downloadable.
ActivitySummary:
type: object
description: Basic activity information identifying the rep and call being scored.
properties:
id:
type: string
format: uuid
description: UUID of the activity.
example: 7efa9c4f-9c47-4922-9ae7-e61a3dbecd72
title:
type: string
description: Title of the activity.
example: Discovery call with Acme Corp
type:
type: string
description: Internal activity type.
example: conference
activityType:
type: string
nullable: true
description: Category name of the activity (e.g. "Discovery Call").
example: Discovery Call
startTime:
type: string
format: date-time
nullable: true
description: Actual start time of the activity in ISO 8601 format.
example: '2024-10-15T09:00:00+00:00'
organizer:
type: object
nullable: true
description: The rep who owns the activity.
properties:
id:
type: string
format: uuid
description: UUID of the user.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name:
type: string
description: Full name of the user.
example: Andrea Smith
email:
type: string
format: email
description: Email address of the user.
example: andrea.smith@company.com
AiScorecard:
type: object
properties:
name:
type: string
description: Name of the scorecard template.
example: Sales Scorecard
totalScore:
type: number
description: Aggregate score across all rules (0–1 scale).
example: 0.87
scoredAt:
type: string
format: date-time
description: ISO 8601 timestamp of when AI scoring completed.
example: '2024-10-15T09:30:00+00:00'
aiScorecardRuleRuns:
type: array
items:
$ref: '#/components/schemas/AiScorecardRuleRun'
AiScorecardResult:
type: object
properties:
activity:
$ref: '#/components/schemas/ActivitySummary'
scorecards:
type: array
description: One entry per scorecard template applied to this activity.
items:
$ref: '#/components/schemas/AiScorecard'
AiScorecardRuleRun:
type: object
properties:
title:
type: string
description: The scoring rule being evaluated.
example: Opened with value proposition
score:
type: number
description: Score achieved for this rule.
example: 1
justification:
type: string
description: AI-generated explanation for the score.
example: Rep clearly stated the value proposition early in the call.
justificationTimestamps:
type: array
description: Speaker moments that support the justification.
items:
type: object
properties:
name:
type: string
description: Speaker name.
example: Andrea
timestamp:
type: string
description: Position in the recording (MM:SS).
example: '00:40'