Prerequisites

Before we begin, make sure you have completed our Developer Quickstart since it covers the necessary elements for integrating with Gig Economy Platforms.

In particular, have close to you your sandbox API Key and your sandbox widget_id.

📘

This tutorial will be followed in Sandbox Mode.

Most Gig Economy platforms have a 2FA step that won't allow for quick tests in production.

1. Create a webhook [Optional]

This is an optional but highly recommended step. Data extraction processes performed by Palenca vary by platform and can go from 10 up to 180 seconds, and webhooks allow you to take action as soon as we have recovered income data for an individual.

Go to the Developers section in your Console and click on the Webhooks tab. Make sure you are in sandbox mode. Go to webhook.site to get a URL to test with for now. Later you will replace this with your API route. Select your sandbox widget so that this webhook is associated to it. Select all webhook events and then click on "Create Webhook".

We have a comprehensive page on Webhooks you can review later on. But right now this is all you need.

2. Open your sandbox widget

3. Simulate a login to a Gig Platform

You don't need real credentials. Here I simulated a login to Uber in Mexico, but you can choose any platform in any country. It's very easy. You can type random usernames, phones, emails, verification codes, and credentials.

I typed "12345".

4. Inspect the webhook events you received

This simple API call should have triggered two different webhook notifications to the URL you provided, login.created and login.success.

The first webhook notification might look something like this (this is the payload of the POST request we made to the URL you provided, easily inspectable in a site like https://webhook.site):

{
  "webhook_url": "https://webhook.site/31f0c91d-a258-475e-800e-80cfd771d017",
  "data": {
    "user_id": "d1c9b98b-3190-479e-99db-04060ff3997f",
    "account_id": "cb39ee15-f29f-427d-9119-0c627575610d",
    "external_id": "None",
    "platform": "uber",
    "status_details": "pending_for_data",
    "webhook_action": "login.created"
  }
}

While the second one might look something like this:

{
  "webhook_url": "https://webhook.site/31f0c91d-a258-475e-800e-80cfd771d017",
  "data": {
    "user_id": "d1c9b98b-3190-479e-99db-04060ff3997f",
    "account_id": "cb39ee15-f29f-427d-9119-0c627575610d",
    "external_id": "None",
    "platform": "uber",
    "status_details": null,
    "webhook_action": "login.success"
  }
}

The following table provides an overview of the four different webhook events we have.

We only have four webhook events (login.created, login.success, login.incomplete, and login.error). We dive deeper into the meaning of each of them in our Webhooks page, but the following image can help you out. Note that only thelogin.success webhook event should trigger your backend to make a request to Palenca's API.

You can check out more details in our Logins page.

You can inspect webhook notifications on your Console too:

5. Visualize the data in the Console

We can see this information in our Console too. Remember that the sandbox toggle needs to be enabled.

If we click on this login, we can see this account's earnings and profile details:

6. Use our API [Optional]

If you're more of an API user, you can call the Gig earnings endpoint. You might also be interested in getting this account's profile via the Profile endpoint.

curl --request POST \
     --url https://sandbox.palenca.com/v1/accounts/<YOUR_ACCOUNT_ID>/earnings/search \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: <SANDBOX_API_KEY>' \
     --data '
{
  "start_date": "2024-09-01",
  "end_date": "2026-03-01",
  "options": {
    "items_per_page": 3
  }
}
'

You will get a response like this:

{
   "success":true,
   "error":null,
   "data":{
      "account_id":"cb39ee15-f29f-427d-9119-0c627575610d",
      "earnings":[
         {
            "amount":179.0,
            "currency":"mxn",
            "earning_date":"2025-03-14",
            "cash_amount":null,
            "count_trips":6
         },
         {
            "amount":246.0,
            "currency":"mxn",
            "earning_date":"2025-03-13",
            "cash_amount":null,
            "count_trips":9
         },
         {
            "amount":53.0,
            "currency":"mxn",
            "earning_date":"2025-03-12",
            "cash_amount":null,
            "count_trips":6
         }
      ]
   },
   "pagination":{
      "page":1,
      "items_per_page":3,
      "total_items":195,
      "total_pages":65
   }
}

And that's it! There's not much to it than that. Users will connect to their Gig Platform via the Palenca widget and you will be notified via webhook events if you're subscribed to them, and the data will always be available in the Console.

Switch to production

If this tutorial made sense to you, try using your production API key and widget ID (make sure you create a production webhook first). You will need to call https://api.palenca.com instead of https://sandbox.palenca.com.