Papaya Global User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Log in to the Papaya Global platform as an admin.
2. Navigate to Settings > Integrations > API Keys.
3. Generate a new API key and copy the token value.
4. Include the token in all requests as: Authorization: Bearer

List Workers

• Method: GET
• URL: https://api.papayaglobal.com/api/v1/workers
• Watch out for: Pagination parameters and exact field names are not fully confirmed in public docs; verify against live API explorer.

Request example

GET /api/v1/workers?page=1&limit=50
Authorization: Bearer <api_key>

Response example

{
  "data": [
    {"id": "w_123", "first_name": "Jane", "last_name": "Doe", "email": "jane@acme.com", "status": "active"}
  ],
  "total": 120,
  "page": 1
}

Get Worker by ID

• Method: GET
• URL: https://api.papayaglobal.com/api/v1/workers/{worker_id}
• Watch out for: Worker ID format must be the Papaya internal UUID, not an external HR system ID.

Request example

GET /api/v1/workers/w_123
Authorization: Bearer <api_key>

Response example

{
  "id": "w_123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@acme.com",
  "country": "US",
  "status": "active"
}

Create Worker

• Method: POST
• URL: https://api.papayaglobal.com/api/v1/workers
• Watch out for: Newly created workers enter 'pending' status and require additional onboarding steps within the platform before becoming 'active'.

Request example

POST /api/v1/workers
Authorization: Bearer <api_key>
Content-Type: application/json

{"first_name":"John","last_name":"Smith","email":"john@acme.com","country":"GB","worker_type":"employee","start_date":"2024-06-01"}

Response example

{
  "id": "w_456",
  "status": "pending",
  "first_name": "John",
  "last_name": "Smith"
}

Update Worker

• Method: PATCH
• URL: https://api.papayaglobal.com/api/v1/workers/{worker_id}
• Watch out for: Country and worker_type changes may be restricted or require manual review by Papaya compliance team.

Request example

PATCH /api/v1/workers/w_456
Authorization: Bearer <api_key>
Content-Type: application/json

{"job_title":"Senior Engineer","department":"Engineering"}

Response example

{
  "id": "w_456",
  "job_title": "Senior Engineer",
  "department": "Engineering"
}

Terminate Worker

• Method: POST
• URL: https://api.papayaglobal.com/api/v1/workers/{worker_id}/terminate
• Watch out for: Termination may trigger country-specific legal workflows; final payroll calculations are handled internally by Papaya.

Request example

POST /api/v1/workers/w_456/terminate
Authorization: Bearer <api_key>
Content-Type: application/json

{"end_date":"2024-12-31","reason":"resignation"}

Response example

{
  "id": "w_456",
  "status": "terminated",
  "end_date": "2024-12-31"
}

List Payroll Records

• Method: GET
• URL: https://api.papayaglobal.com/api/v1/payroll
• Watch out for: Payroll data availability depends on payroll cycle completion; real-time data may not be available mid-cycle.

Request example

GET /api/v1/payroll?worker_id=w_123&year=2024
Authorization: Bearer <api_key>

Response example

{
  "data": [
    {"payroll_id": "pr_789", "worker_id": "w_123", "period": "2024-11", "net_pay": 5000, "currency": "USD"}
  ]
}

• Rate limits: Specific rate limit values are not publicly documented by Papaya Global.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No official rate limit documentation found. Contact Papaya Global support for enterprise-tier limits.

• Pagination method: offset

• Default page size: Not documented

• Max page size: Not documented

• Pagination pointer: page / limit (inferred from API explorer; not fully documented publicly)

• Webhooks available: Unknown

• Webhook notes: Webhook support is not explicitly documented in publicly available Papaya Global developer documentation. Availability is unconfirmed.

• Alternative event strategy: Poll the workers and payroll endpoints periodically to detect status changes.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Unknown
• Endpoint: Not documented

Limitations:

• No SCIM provisioning documented in official Papaya Global developer or help center documentation.
• IdP integrations (Okta, Entra ID, Google Workspace, OneLogin) are not listed as supported per available data.

Three primary integration scenarios are supported by the documented endpoints.

Onboard a new international employee: POST /api/v1/workers with required fields (first_name, last_name, email, country, worker_type, start_date, salary). The worker enters pending status and does not become payroll-eligible automatically - Papaya's compliance team must complete country-specific onboarding steps before status transitions to active. Poll GET /api/v1/workers/{worker_id} to monitor the transition.

Sync workforce roster to an internal HRIS: GET /api/v1/workers with pagination (offset-based; exact param names inferred from API explorer, not fully confirmed). Map id, email, status, country, and department to your internal schema. Store Papaya's worker_id as the external reference key. No delta endpoint exists - full roster pulls are required to detect changes.

Terminate an employee and retrieve final payroll: POST /api/v1/workers/{worker_id}/terminate with end_date and reason. Confirm terminated status via GET, then retrieve the final payroll record via GET /api/v1/payroll?worker_id={worker_id} after the payroll cycle closes. Final payroll records may not be immediately available; Papaya processes statutory payments internally before the record surfaces via API.

Onboard a new international employee

1. POST /api/v1/workers with required fields: first_name, last_name, email, country, worker_type, start_date, salary.
2. Receive worker_id and 'pending' status in response.
3. Monitor worker status via GET /api/v1/workers/{worker_id} until status transitions to 'active' (may require manual Papaya onboarding steps).
4. Update additional profile fields (department, job_title, manager_id) via PATCH /api/v1/workers/{worker_id}.

Watch out for: Workers do not become active automatically; Papaya's compliance team may need to complete country-specific onboarding steps before the worker is payroll-eligible.

Sync workforce roster to an internal HRIS

1. GET /api/v1/workers with pagination params to retrieve all workers.
2. Iterate pages until total count is exhausted.
3. Map Papaya worker fields (id, email, status, country, department) to internal HRIS schema.
4. Store Papaya worker_id as the external reference key for future updates.

Watch out for: No delta/changelog endpoint is documented; full roster sync is required to detect changes unless webhooks become available.

Terminate an employee and retrieve final payroll

1. POST /api/v1/workers/{worker_id}/terminate with end_date and reason.
2. Confirm status is 'terminated' via GET /api/v1/workers/{worker_id}.
3. After payroll cycle closes, GET /api/v1/payroll?worker_id={worker_id} to retrieve final payroll record.
4. Reconcile net_pay and currency against internal finance records.

Watch out for: Final payroll may not be immediately available via API; Papaya processes country-specific statutory payments internally and the payroll record may only appear after the cycle is finalized.

The most significant integration risk is the absence of documented rate limits, pagination maximums, and error code schemas - all three must be empirically tested in a sandbox before production use. Salary and compensation changes via PATCH may trigger internal payroll recalculation workflows that cannot be reversed through the API alone.

Country-specific compliance rules affect which fields are required or mutable on a per-worker basis; automating updates without per-country validation introduces compliance exposure. The country and worker_type fields on an existing worker may be restricted or require manual review by Papaya's compliance team - treat these as effectively immutable post-creation until confirmed otherwise.

Webhook support is unconfirmed, making event-driven architectures unreliable against this API today. Any pipeline that depends on real-time status changes must fall back to polling, with the attendant risk of acting on stale data mid-payroll cycle.