Skip to main content
API docs by Redocly

Palenca API (1.0)

On this page we list all the methods available in the Palenca API, as well as the complete reference of the parameters that each one accepts.

The Palenca API is designed with the REST standard in mind. The API endpoints are grouped by resources, have predictable URLs, responses are formatted in JSON, and we use standard HTTP response, authentication, and verb codes.

We have 2 environments: Sandbox and Production.

Sandbox: https://sandbox.palenca.com/v1

Production: https://api.palenca.com/v1

Before joining, we recommend that you familiarize yourself with the Entities that we manage in Palenca (Users, Accounts, Logins)

Users

Create User

Register a new user in Palenca. A user represents a formal or gig economy worker.

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
widget_id
required
string <uuid>

required: Id of the Widget to which the user will be associated

external_id
string

optional: External unique identifier of the client (provided by your own application)

Responses

Request samples

Content type
application/json
{
  • "widget_id": "2b0956a2-58e7-4e97-804d-2852d40f05d7",
  • "external_id": "1234567890"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "mistake": { }
}

Retrieve User

Returns the user corresponding to the specified id.

path Parameters
required
User Id (string) or User Id (string)

User ID to obtain

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Delete User

Elimina el usuario correspondiente al id especificado.

path Parameters
user_id
required
string <uuid>

ID del usuario a eliminar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": null
}

Retrieve User Accounts

Returns the user accounts corresponding to the specified user id.

path Parameters
required
User Id (string) or User Id (string)

User ID to obtain

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

List Users

Returns a paginated list of users created within a date range.

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
start_date
required
string

required: Start date of the search in YYYY-MM-DD format

end_date
required
string

required: End date of the search in YYYY-MM-DD format

object
Default: {"items_per_page":100,"page":1}

optional: Pagination options

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    }
}

Create User And Account

Register a user along with their corresponding account in a single request. A user represents a formal or gig economy worker and an account represents an account of the worker on a specific platform . Currently available for IMSS and ISSSTE. If you want to use this endpoint to create gig economy accounts, contact us at support@palenca.com

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
widget_id
string <uuid>

optional: Id of the Widget to which the user will be associated

external_id
string

optional: External unique identifier of the client (provided by your own application)

country
required
any
Value: "mx"

requerido: País

platform
required
any
Enum: "imss" "issste"

requerido: Plataforma con la cual se quiere hacer la conexión.

identifier
required
string

required: User identifier (CURP).

Responses

Request samples

Content type
application/json
{
  • "widget_id": "2b0956a2-58e7-4e97-804d-2852d40f05d7",
  • "external_id": "1234567890"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Accounts

Retrieve User Accounts

Returns the user accounts corresponding to the specified user id.

path Parameters
required
User Id (string) or User Id (string)

User ID to obtain

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Retrieve Account User

Returns the user associated with the account.

path Parameters
account_id
required
string <uuid>

requerido: Id of the account to fetch.

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Create Account

Register a new account corresponding to a user. An account represents a worker account on a specific platform. Currently available for IMSS and ISSSTE. If you want to use this endpoint to create gig economy accounts * contact us at support@palenca.com

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
country
required
any
Value: "mx"

requerido: País

platform
required
any
Enum: "imss" "issste"

requerido: Plataforma con la cual se quiere hacer la conexión.

identifier
required
string

requerido: Identificador del usuario (CURP)

user_id
required
string <uuid>

requerido: Id del usuario al que estará asociada la cuenta

Responses

Request samples

Content type
application/json
{
  • "country": "mx",
  • "platform": "uber",
  • "identifier": "user@example.com",
  • "identifier_type": "email",
  • "password": "s3cur3p4s5w0rd"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Retrieve Account

Regresa la cuenta correspondiente al id especificado.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta a obtener

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Delete Account

Elimina la cuenta correspondiente al id especificado.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta a eliminar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": null
}

Logins

List Logins

Returns a paginated list of logins created within a date range.

header Parameters
x-api-key
string

Unique private key for each organization, enabling requests in both Sandbox and Production environments.

Request Body schema: application/json
start_date
required
string

required: Start date of the search in YYYY-MM-DD format

end_date
required
string

required: End date of the search in YYYY-MM-DD format

object
Default: {"items_per_page":100,"page":1}

optional: Pagination options

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    }
}

Profile

Retrieve Account Profile

Returns the profile data of the worker that belongs to the account specified on the account_id.

path Parameters
account_id
required
string <uuid>

required: Id of the account for which you want to obtain the profile

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Employment Mexico

Retrieve Account Employment

Returns the employment data of the formal worker (IMSS, ISSSTE), corresponding to the account specified by the id.

path Parameters
account_id
required
string <uuid>

required: Id of the account for which you want to obtain the employment information

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Employment Brazil

Retrieve Account Employment History

Returns the employment history data of the worker that belongs to the account specified on the account_id.

path Parameters
account_id
required
string <uuid>

required: Id of the account for which you want to obtain the employment information

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Gig earnings

Retrieve Account Earnings

Returns a paginated list with the earnings data of the gig economy worker (Uber, Rappi, Didi, etc.), corresponding to the account specified by the id.

path Parameters
account_id
required
string <uuid>

required: Id of the account for which you want to obtain the profits

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
start_date
required
string

required: Start date of the search in YYYY-MM-DD format

end_date
required
string

required: End date of the search in YYYY-MM-DD format

object
Default: {"items_per_page":100,"page":1}

optional: Pagination options

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    },
  • "account_id": "e28f45c2-b137-407c-9aed-adaac2765b36"
}

CDT earnings

Retrieve payment history of a Carteira de Trabalho account

Returns a paginated list of the payment history information of a worker inside the Carteira de Trabalho (CDT) account specified on the account_id.

path Parameters
account_id
required
string <uuid>

required: Id of the account for which you want to obtain the profits

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
start_date
required
string

required: Start date of the search in YYYY-MM-DD format

end_date
required
string

required: End date of the search in YYYY-MM-DD format

object
Default: {"items_per_page":100,"page":1}

optional: Pagination options

Responses

Request samples

Content type
application/json
{
  • "start_date": "string",
  • "end_date": "string",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    },
  • "pagination": {
    }
}

Employment insights

Retrieve Employment Insights

Returns the employment insights of the formal worker (IMSS, ISSSTE), corresponding to the account specified by the ID. Palenca insights offer a list of pre-calculated variables that help risk and data science to make decisions with a greater degree of certainty.

path Parameters
account_id
required
string <uuid>

required: ID of the account for which you want to obtain employment information

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Generate Employment Trends PDF

Generates a PDF file detailing the employment trends for the specified account, associated with IMSS and ISSSTE. This endpoint is exclusively for the creation of the PDF and the process takes approximately 1 minute.

After generation, the PDF can be retrieved via the 'employment_files' key within the response of the employment endpoint. This key contains an array of files related to employment history, including the newly generated PDF. For detailed information on accessing the generated PDF and understanding the response structure, please refer to the employment endpoint documentation.

⚠ This endpoint is not available in the Sandbox environment.

path Parameters
account_id
required
string <uuid>

Required: The account ID for which the employment trends PDF is to be generated.

header Parameters
x-api-key
string

Unique private key for each organization, enabling requests in both Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": { }
}

Gig insights

Retrieve Gig Insights

Regresa los insights de ganancias del trabajador de la gig economy (Uber, Rappi, Didi, etc.), correspondientes a la cuenta especificada mediante el id. Los insights de Palenca ofrecen una lista de variables precalculadas que ayudan a los equipos de riesgos y ciencia de datos a tomar decisiones con mayor grado de certeza.

path Parameters
account_id
required
string <uuid>

requerido: Id de la cuenta para la cual se quieren obtener los insighs de ganancias (gig economy)

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Widgets

Retrieve Widget

Returns the widget corresponding to the specified id.

path Parameters
widget_id
required
string <uuid>

required: Id of the widget to obtain

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Update widget

Update widget.

Request Body schema: application/json
name
string

Name of the widget

countries
Array of strings

Countries to display in the widget

platforms
Array of strings

Platforms to display in the widget

require_gov_id
boolean

Adds an extra step to request the Government ID (CURP, CPF, etc.) from the user

hide_logo
boolean

Hides the logo in the widget

hide_whatsapp
boolean

Hides the Whatsapp icon in the widget

hide_consent
boolean

Hides the consent screen in the widget

font_family
string

Font for modifying the text in the widget, must exist in Google Fonts

primary_color
string

Primary color to modify the widget in hexadecimal format (#FFFFFF)

border_radius
string

Defines the border radius for buttons and form fields (round, rounded, square)

custom_privacy_url
string

URL of the terms and conditions to display in the widget

whatsapp_number
string

Whatsapp number to receive messages from users

Responses

Request samples

Content type
application/json
{
  • "countries": [
    ],
  • "platforms": [
    ],
  • "require_gov_id": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

List Widgets

Returns a list of registered widgets.

query Parameters
is_sandbox
boolean
Default: false

optional: Environment to which the widgets to be obtained correspond

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": [
    ]
}

Create widget

Create a new widget.

Request Body schema: application/json
name
required
string

required: Name of the widget

countries
required
Array of strings

required: Countries to display in the widget

platforms
required
Array of strings

required: Platforms to display in the widget

is_sandbox
required
boolean

required: Environment of the widget (sandbox or production)

require_gov_id
boolean

Adds an extra step to request the Government ID (CURP, CPF, etc.) from the user

Responses

Request samples

Content type
application/json
{
  • "name": "My sandbox widget",
  • "countries": [
    ],
  • "platforms": [
    ],
  • "is_sandbox": true,
  • "require_gov_id": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Webhooks

Create Webhook

Registra un nuevo webhook. Para más información puedes consultar nuestra guía

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Request Body schema: application/json
url
required
string

required: webhook URL

name
string

required: Name to assign to the webhook

widget_id
required
string <uuid>

required: Widget ID to which the webhook will be associated

is_sandbox
required
boolean

required: Webhook environment (sandbox or production)

sign_request
boolean
Default: false

optional: Parameter to define whether notifications to the webhook will be signed (hmac)

Responses

Request samples

Content type
application/json
{
  • "url": "https://domain.com/webhook",
  • "name": "My webhook",
  • "is_sandbox": true,
  • "sign_request": false,
  • "widget_id": "b679c2fb-a096-4c26-a902-245f9bce66d9"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

List Webhooks

Returns a list of registered webhooks.

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": { },
  • "error": { }
}

Retrieve Webhook

Returns the webhook corresponding to the specified id.

path Parameters
webhook_id
required
string <uuid>

required: Id of the webhook to obtain

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Update Webhook

Updates the webhook corresponding to the specified id.

path Parameters
webhook_id
required
string <uuid>

required: Id of the webhook to update

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
url
string

opcional: URL del webhook

name
string

opcional: Nombre a asignar al webhook

widget_id
string <uuid>

opcional: Widget ID al que estará asociado el webhook

is_sandbox
boolean

opcional: Entorno del webhook (sandbox o producción)

sign_request
boolean

opcional: Parámetro para definir si las notificaciones al webhook estarán firmadas (hmac)

is_active
boolean

opcional: Parámetro para activar o desactivar el webhook

Responses

Request samples

Content type
application/json
{
  • "url": "https://domain.com/webhook",
  • "name": "My webhook",
  • "is_sandbox": true,
  • "is_active": true,
  • "sign_request": false,
  • "widget_id": "b679c2fb-a096-4c26-a902-245f9bce66d9"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Delete Webhook

Elimina el webhook correspondiente al id especificado.

path Parameters
webhook_id
required
string <uuid>

requerido: Id del webhook a eliminar

header Parameters
x-api-key
string

Llave privada única por organización. Permite realizar peticiones en los ambientes Sandbox y Producción.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": null
}

Consents

Retrieve Consents by Government ID

Returns the consents corresponding to the specified Government ID.

path Parameters
gov_id
required
string

The Government ID to retrieve consents.

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": {
    }
}

Search Consents

Searches for consents within a specified date range with pagination options.

header Parameters
x-api-key
string

Unique private key per organization. Allows requests to be made in Sandbox and Production environments.

Request Body schema: application/json
start_date
string <date>
end_date
string <date>
object

Responses

Request samples

Content type
application/json
{
  • "start_date": "2020-08-03",
  • "end_date": "2025-07-03",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": null,
  • "data": [
    ]
}