PayDesk API | Genaya API Reference

Money

PayDesk

Payroll - commissions, runs and pay periods. Read-only.

GET/paydesk-commissions

List commissions

Returns commission records, including which rule produced each amount. Read-only. Requires scope: paydesk:read. To keep a copy in sync, walk the plain list once, then poll with updated_since: every change to a commission (created, recomputed, adjusted, locked, paid, reversed) moves its updatedAt, and a commission is never deleted - a reversal arrives as status reversed. updated_since cannot be combined with employeeId, status or appointmentId - combining them returns 400 (code conflicting_filters).

Parameters

Query

employeeId

string

Return only commissions matching this employeeId.

status

string

Return only commissions matching this status.

appointmentId

string

Return only commissions matching this appointmentId.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/paydesk-commissions \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "commission",
      "employeeId": "",
      "employeeName": "",
      "amount": 0,
      "currency": "",
      "status": "",
      "ruleName": "",
      "ruleSource": "",
      "customRate": {
        "type": "percent",
        "value": 0
      },
      "appointmentId": "",
      "appointmentNumber": 0,
      "appointmentTotal": 0,
      "appointmentScheduledAt": "2026-01-15T09:30:00.000Z",
      "triggerAt": "2026-01-15T09:30:00.000Z",
      "eligibleAt": "2026-01-15T09:30:00.000Z",
      "paidAt": "2026-01-15T09:30:00.000Z",
      "reversedAt": "2026-01-15T09:30:00.000Z",
      "reversalReason": "",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

GET/paydesk-commissions/{id}

Retrieve a commission

Returns a single commission by id. A record belonging to another organization returns 404 rather than 403. Requires scope: paydesk:read.

Parameters

Path

idrequired

string

Response 200

FieldTypeDescription

id

string

object

string

employeeId

string

nullable

employeeName

string

nullable

amount

number

nullable

currency

string

status

string

nullable

ruleName

string

Which rule produced this amount.nullable

ruleSource

string

Where the rule came from: member (the payee's own rule), orgRule (a Performance Pay rule), fallback (the payee's flat percent), none (no rule matched), vendorBaseRate (the vendor's base rate) or customRate (a custom rate set on this appointment for this payee).nullable

customRate

object

Custom rate set on the appointment for this payee, when ruleSource is customRate. Null for every other rule source.nullable

type

enumpercent | flat

percent of the payee's commission base, or a flat amount in the commission's currency.

value

number

appointmentId

string

nullable

appointmentNumber

integer

nullable

appointmentTotal

number

nullable

appointmentScheduledAt

string <date-time>

nullable

triggerAt

string <date-time>

nullable

eligibleAt

string <date-time>

nullable

paidAt

string <date-time>

nullable

reversedAt

string <date-time>

nullable

reversalReason

string

nullable

createdAt

string <date-time>

updatedAt

string <date-time>

nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/paydesk-commissions/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "commission",
    "employeeId": "",
    "employeeName": "",
    "amount": 0,
    "currency": "",
    "status": "",
    "ruleName": "",
    "ruleSource": "",
    "customRate": {
      "type": "percent",
      "value": 0
    },
    "appointmentId": "",
    "appointmentNumber": 0,
    "appointmentTotal": 0,
    "appointmentScheduledAt": "2026-01-15T09:30:00.000Z",
    "triggerAt": "2026-01-15T09:30:00.000Z",
    "eligibleAt": "2026-01-15T09:30:00.000Z",
    "paidAt": "2026-01-15T09:30:00.000Z",
    "reversedAt": "2026-01-15T09:30:00.000Z",
    "reversalReason": "",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

GET/paydesk-payroll-runs

List payroll runs

Returns payroll runs with their range totals. Per-employee breakdowns are not exposed here. Read-only. Requires scope: paydesk:read.

Parameters

Query

status

string

Return only payroll runs matching this status.

frequency

string

Return only payroll runs matching this frequency.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/paydesk-payroll-runs \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "payroll_run",
      "status": "",
      "frequency": "",
      "rangeLabel": "",
      "periodStart": "2026-01-15T09:30:00.000Z",
      "periodEnd": "2026-01-15T09:30:00.000Z",
      "currency": "",
      "employeeCount": 0,
      "totals": {},
      "paymentMethod": "",
      "paymentReference": "",
      "finalizedAt": "2026-01-15T09:30:00.000Z",
      "finalizedByName": "",
      "paidAt": "2026-01-15T09:30:00.000Z",
      "paidByName": "",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

GET/paydesk-payroll-runs/{id}

Retrieve a payroll run

Returns a single payroll run by id. A record belonging to another organization returns 404 rather than 403. Requires scope: paydesk:read.

Parameters

Path

idrequired

string

Response 200

FieldTypeDescription

id

string

object

string

status

string

nullable

frequency

string

nullable

rangeLabel

string

nullable

periodStart

string <date-time>

nullable

periodEnd

string <date-time>

nullable

currency

string

employeeCount

integer

totals

object

nullable

paymentMethod

string

nullable

paymentReference

string

nullable

finalizedAt

string <date-time>

nullable

finalizedByName

string

nullable

paidAt

string <date-time>

nullable

paidByName

string

nullable

createdAt

string <date-time>

updatedAt

string <date-time>

nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/paydesk-payroll-runs/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "payroll_run",
    "status": "",
    "frequency": "",
    "rangeLabel": "",
    "periodStart": "2026-01-15T09:30:00.000Z",
    "periodEnd": "2026-01-15T09:30:00.000Z",
    "currency": "",
    "employeeCount": 0,
    "totals": {},
    "paymentMethod": "",
    "paymentReference": "",
    "finalizedAt": "2026-01-15T09:30:00.000Z",
    "finalizedByName": "",
    "paidAt": "2026-01-15T09:30:00.000Z",
    "paidByName": "",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

GET/paydesk-pay-periods

List pay periods

Returns per-employee pay periods. Read-only. Requires scope: paydesk:read.

Parameters

Query

employeeId

string

Return only pay periods matching this employeeId.

status

string

Return only pay periods matching this status.

frequency

string

Return only pay periods matching this frequency.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/paydesk-pay-periods \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "pay_period",
      "employeeId": "",
      "employeeName": "",
      "label": "",
      "status": "",
      "frequency": "",
      "periodStart": "2026-01-15T09:30:00.000Z",
      "periodEnd": "2026-01-15T09:30:00.000Z",
      "weekStart": "",
      "runId": "",
      "closedAt": "2026-01-15T09:30:00.000Z",
      "closedByName": "",
      "closedReason": "",
      "reopenedAt": "2026-01-15T09:30:00.000Z",
      "reopenReason": "",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

GET/commission-reports

List commission reports

Returns the saved commission report snapshots - the documents generated in PayDesk for a date window, newest first. Summary figures only; the frozen per-appointment rows are not returned by this endpoint. Read-only. Requires scope: paydesk:read.

Parameters

Query

from

string

Return only reports GENERATED on or after this date. Accepts an ISO-8601 date (2026-06-01, snapped to the start of the UTC day) or a full timestamp. Mutually exclusive with period_from / period_to.

to

string

Return only reports GENERATED on or before this date. Accepts an ISO-8601 date (2026-06-30, snapped to the end of the UTC day) or a full timestamp. Mutually exclusive with period_from / period_to.

period_from

string

Return only reports whose COVERED period starts on or after this date. Results are ordered by covered-period start, newest first. Mutually exclusive with from / to - combining them returns 400 (code conflicting_filters).

period_to

string

Return only reports whose COVERED period starts on or before this date. Mutually exclusive with from / to.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/commission-reports \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "commission_report",
      "rangeLabel": "",
      "startMs": 0,
      "startDate": "2026-01-15T09:30:00.000Z",
      "endMs": 0,
      "endDate": "2026-01-15T09:30:00.000Z",
      "groupBy": "employee",
      "currency": "",
      "generatedAt": "2026-01-15T09:30:00.000Z",
      "generatedByName": "",
      "totals": {
        "commission": 0,
        "revenue": 0,
        "taxes": 0,
        "costs": 0,
        "orgCommission": 0,
        "net": 0,
        "appointmentCount": 0,
        "payeeCount": 0
      }
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

GET/commission-reports/{id}

Retrieve a commission report

Returns one saved commission report - the same summary the list returns, plus one row per group (team member, external, vendor, company or the organization, depending on groupBy). A report belonging to another organization returns 404 rather than 403. Requires scope: paydesk:read.

Parameters

Path

idrequired

string

Response 200

No fields.

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

GET/commission-reports/{id}/image

Render a commission report as a PNG

Renders the report's summary page - hero total, stat tiles and both donut charts - as a PNG sized for a phone screen, so it can be posted straight into a chat or messaging channel. It is the same branded document the PDF export produces, cropped to its first page; the per-team sections and money-view tables are omitted. By default the image is returned base64-encoded inside the normal data envelope, because messaging APIs need either base64 or a publicly fetchable URL and this endpoint is bearer-authenticated. Pass format=png for the raw image/png bytes. Requires scope: paydesk:read.

Parameters

Path

idrequired

string

Query

width

integer

Output width in pixels (540-2160, default 1080). The layout is fixed; this only changes the resolution it is rasterized at.

format

string

json (default) returns the base64 envelope; png returns raw image/png bytes.

Response 200

FieldTypeDescription

id

string

object

string

mimeType

string

width

integer

Pixel width of the rendered image.nullable

height

integer

Pixel height of the rendered image.nullable

byteSize

integer

Size of the decoded PNG in bytes.

filename

string

base64

string

The PNG bytes

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/commission-reports/{id}/image \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "commission_report_image",
    "mimeType": "image/png",
    "width": 0,
    "height": 0,
    "byteSize": 0,
    "filename": "",
    "base64": ""
  }
}

GET/paydesk-pay-periods/{id}

Retrieve a pay period

Returns a single pay period by id. A record belonging to another organization returns 404 rather than 403. Requires scope: paydesk:read.

Parameters

Path

idrequired

string

Response 200

FieldTypeDescription

id

string

object

string

employeeId

string

nullable

employeeName

string

nullable

label

string

nullable

status

string

nullable

frequency

string

nullable

periodStart

string <date-time>

nullable

periodEnd

string <date-time>

nullable

weekStart

string

nullable

runId

string

nullable

closedAt

string <date-time>

nullable

closedByName

string

nullable

closedReason

string

nullable

reopenedAt

string <date-time>

nullable

reopenReason

string

nullable

createdAt

string <date-time>

updatedAt

string <date-time>

nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/paydesk-pay-periods/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "",
    "object": "pay_period",
    "employeeId": "",
    "employeeName": "",
    "label": "",
    "status": "",
    "frequency": "",
    "periodStart": "2026-01-15T09:30:00.000Z",
    "periodEnd": "2026-01-15T09:30:00.000Z",
    "weekStart": "",
    "runId": "",
    "closedAt": "2026-01-15T09:30:00.000Z",
    "closedByName": "",
    "closedReason": "",
    "reopenedAt": "2026-01-15T09:30:00.000Z",
    "reopenReason": "",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}