Public leads API: OAuth2 and examples

Portal Hero is launching a new endpoint in its public API that lets dealers receive leads from any external source directly in their CRM. Web forms, landing pages, Google Ads campaigns, third-party integrations... all leads centralised in a single place.

For the business: all your leads in one place

Until now, the leads that reached your Portal Hero CRM came exclusively from conversations on the marketplaces where you publish your products. The system detected them automatically and turned them into sales opportunities.

With the new lead ingestion endpoint, that limitation disappears. You can now connect any customer acquisition source with your Portal Hero CRM:

• Contact form on your website: each submission automatically creates a lead in your CRM with the customer's details and the product they are interested in.
• Google Ads campaign landing pages: set up a webhook that, on receiving a form, sends the data directly to Portal Hero.
• Automation tools (Zapier, Make, n8n): connect any lead source with a simple HTTP connector.
• Full centralisation: no matter where the lead comes from, they are all managed from the same panel.

The result is a complete view of all your sales opportunities, without having to switch between platforms or lose leads along the way.

No duplicates, no complications

The endpoint is smart: if a customer already exists in your CRM (identified by their phone or email), a new one is not created. If they already have an open sales opportunity, the new products are added to that existing opportunity. And if a product was already associated, it is simply ignored. All of this happens automatically, without you having to worry about duplicates.

For the developer: integration guide

The endpoint is available in the Portal Hero public API. Below is everything you need to integrate it.

Authentication

The API uses OAuth2 with a Bearer token. First obtain a token with the Portal Hero account credentials:

curl -X POST https://public.api.portalhero.pro/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=tu_email@ejemplo.com" \
  -d "password=tu_contraseña"

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

Send a lead

With the token, you can now send leads to the CRM. The body has three main fields:

• customer (required): customer details. At least phone or email is required.
• items (optional): array of catalogue products referenced by their external_id.
• source (optional): the lead's origin (for example "web_form", "google_ads"). Defaults to "api".

If the account has multiple shops, add the query param user_id to indicate which one to send the lead to.

curl -X POST https://public.api.portalhero.pro/leads \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "phone": "+34612345678",
    "email": "cliente@example.com",
    "first_name": "Carlos",
    "last_name": "García"
  },
  "items": [
    { "external_id": "MOTO-001" }
  ],
  "source": "web_form"
}'

Response

The API returns a JSON with the result of the operation, indicating whether a new customer was created or an existing one reused, and likewise for the sales opportunity:

{
  "customer_id": 42,
  "opportunity_id": 15,
  "items_added": 1,
  "created_customer": true,
  "created_opportunity": true
}

Idempotent behaviour

• If the customer (by phone or email) already exists, they are reused.
• If they already have an open sales opportunity, the items are added to the existing one.
• If an item is already in the opportunity, it is ignored without error.
• Items with an external_id not found in the catalogue are skipped with a warning, without the request failing.

Complete example: from token to lead

This is the complete flow to obtain a token and create a lead from a web form:

Step 1: Obtain the access token

curl -X POST https://public.api.portalhero.pro/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=tu_email@ejemplo.com" \
  -d "password=tu_contraseña"

Step 2: Send the lead

curl -X POST https://public.api.portalhero.pro/leads \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer": {
    "phone": "+34612345678",
    "email": "carlos.garcia@email.com",
    "first_name": "Carlos",
    "last_name": "García"
  },
  "items": [
    { "external_id": "MOTO-001" }
  ],
  "source": "web_form"
}'

Step 3: Verify in the dashboard

Go to the Portal Hero CRM and check that the lead appears with the customer's details and the associated product. If the customer already existed, you will see the product added to their open opportunity.

If you need help with the integration or have questions about any use case, our technical support team is at your disposal.