Guides
API StatusCreate Sandbox Account
Start typing to search…

Tutorial: Integrate with IMSS

A hands-on guide to get your application up and running with our most popular integration.

Prerequisites

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

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


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 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. Create an IMSS account

In this step we will create a user (which represents a worker) and an account (which represents a connection to a given platform, in this case IMSS) by making a POST request to the endpoint /users /accounts. You can check out more details on this endpoint here .

Note that we are calling the sandbox API. Make sure you are using your sandbox API Keys.

We're using one of our own CURP's here to help you out, but you can replace GATA000408HTLRLLA7 with any valid CURP you want to test Palenca with.

curl --location --request POST 'https://sandbox.palenca.com/v1/users/accounts' \
--header 'x-api-key: SANDBOX_PRIVATE_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
     "identifier": "GATA000408HTLRLLA7",
     "country": "mx",
     "platform": "imss",
     "widget_id": "YOUR_SANDBOX_WIDGET_ID"
}'
const axios = require('axios');

const data = JSON.stringify({
  identifier: 'GATA000408HTLRLLA7', // Replace with the CURP you want to consult
  country: 'mx',
  platform: 'imss',
  widget_id: 'YOUR_SANDBOX_WIDGET_ID'
});

const config = {
  method: 'POST',
  url: 'https://sandbox.palenca.com/v1/users/accounts',
  headers: {
    'x-api-key': 'SANDBOX_PRIVATE_API_KEY',
    'Content-Type': 'application/json',
  },
  data: data,
};

(async () => {
  try {
    const { data: responseData } = await axios(config);
    console.info(JSON.stringify(responseData));
  } catch (error) {
    console.error(error);
  }
})();
import requests
import json

headers = {
    "Content-Type": "application/json",
    "x-api-key": "SANDBOX_PRIVATE_API_KEY"
}

payload = {
    "identifier": "GATA000408HTLRLLA7",
    "platform": "imss",
    "country": "mx",
    "widget_id": "YOUR_SANDBOX_WIDGET_ID"
}

response = requests.post(
    "https://sandbox.palenca.com/v1/users/accounts",
    headers=headers,
    data=json.dumps(payload)
)

print(response.json())

You should see a response like this, which means the process to obtain employment data has started:

{
   "success":true,
   "error":null,
   "data":{
      "user_id":"5666d5d1-a01a-4261-8dfe-0f9d41f8dfc0",
      "country":"mx",
      "platform":"imss",
      "account_id":"ee64a864-60a7-4a53-bbe6-e08d5d3f3f44",
      "next_step":null,
      "methods":[],
      "alternative_methods":[],
      "hint":null
   }
}

Don't worry about all the fields for now. The important part is that we now have an account_id associated to this CURP. Copy theaccount_id.

3. 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/aa693cf6-4d5a-43e1-afca-1f00adeb3616",
  "data": {
    "user_id": "5666d5d1-a01a-4261-8dfe-0f9d41f8dfc0",
    "account_id": "ee64a864-60a7-4a53-bbe6-e08d5d3f3f44",
    "external_id": "None",
    "platform": "imss",
    "status_details": "pending_for_data",
    "webhook_action": "login.created"
  }
}

While the second one might look something like this:

{
  "webhook_url": "https://webhook.site/aa693cf6-4d5a-43e1-afca-1f00adeb3616",
  "data": {
    "user_id": "5666d5d1-a01a-4261-8dfe-0f9d41f8dfc0",
    "account_id": "ee64a864-60a7-4a53-bbe6-e08d5d3f3f44",
    "external_id": "None",
    "platform": "imss",
    "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.

Later in this tutorial we provide CURPs that help you test out error scenarios.

You can inspect webhook notifications on your Console too:


4. Retrieve employment data

If you did not receive a login.successwebhook notification, we recommend going back to step #2 of this tutorial and use the CURP we provided, double checking that you are using both a sandbox API key and a sandbox widget_id.

If you received a login.successwebhook notification, we are ready to recover the worker's employment history. Copy the account_id you received in step 1 and paste it in the following request:

curl --request GET \
     --url https://sandbox.palenca.com/v1/accounts/<ACCOUNT_ID>/employment \
     --header 'x-api-key: SANDBOX_PRIVATE_API_KEY' \
     --header 'accept: application/json'

const axios = require('axios');

const fetchEmploymentData = async (accountId) => {
    const config = {
        method: 'GET',
        url: `https://sandbox.palenca.com/v1/accounts/${accountId}/employment`,
        headers: {
            'x-api-key': 'SANDBOX_PRIVATE_API_KEY',
            'accept': 'application/json'
        }
    };

    try {
        const { data } = await axios(config);
        console.log(data);
    } catch (error) {
        console.error('Error fetching employment data:', error);
    }
};

// Replace <ACCOUNT_ID> with the actual account ID
fetchEmploymentData('<ACCOUNT_ID>');
import requests

def fetch_employment_data(account_id):
    url = f"https://sandbox.palenca.com/v1/accounts/{account_id}/employment"
    headers = {
        "x-api-key": "SANDBOX_PRIVATE_API_KEY",
        "accept": "application/json"
    }
    
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        print(response.json())
    except requests.exceptions.RequestException as error:
        print(f"Error fetching employment data: {error}")

        
# Replace <ACCOUNT_ID> with the actual account ID
fetch_employment_data("<ACCOUNT_ID>")

You will get a response that simulates the data we provide for successful IMSS connections!

Note: You can call the exact same endpoint but replacing /employment for /profile to get a simulation of the profile information we provide for IMSS accounts.

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 employment and profile details:

We can even export their employment history in a CSV, as shown in the picture above.

6. Test other webhook events.

We have just tested the login.created and login.successwebhook events. Further below we provide you with different CURPs that allow you to trigger the login.incompleteand login.error webhook events.

Simply choose one of these CURPs and use it in the request we provided in step #2 to get different webhook events. Note: to receive these events, your webhook must be subscribed to them in the first place. If you're unsure this is the case, you can go back to the_Developers_ section, click on the_Webhooks_ tab, click on_edit_ and then select all the events you want to listen to.


CURPs that trigger the login.successwebhook event

These CURPs will create logins with complete profile and employment information.

  • LALE870908HDFRPD02
  • JITM910411HASMMR08

CURPs that trigger the login.successwebhook event without having employment information

A person that has never had a formal job might perfectly have a CURP that has no employment information associated to it in IMSS. This is also the case for some students with IMSS access but no salary.

  • ZUAL000827HMCXRSA8
  • AATE910411HASLMG07

CURPs that trigger the login.incompletewebhook event

  • POTP910411HASBMP04 (error details: curp_has_inconsistencies)
  • MEMC760502MMCJGR00 (error details: nss_not_found_in_imss; nss means "número de seguridad social")

CURPs that trigger the login.error webhook event

  • AUAT940412HCLQQM08 (error details: service_degradation)
  • DETJ910411HASLMR04 (error details: service_degradation)

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.

Updated about 19 hours ago

What’s Next