Sales in JSONLead format: specification

JSONLead sales specification: fields, three delivery methods and a complete reference table.

This format remains in use for existing integrations. For new integrations, the recommended format is the versioned schema ph.order/1.2.

Automating your sales flow and connecting it with your management system or ERP has never been so easy. With our system, every sale made on the portal is sent in a structured way so you can process it automatically without complications. Here we explain how it works and how you can implement this integration.

Delivery format: JSONLead as a market standard

To guarantee compatibility and ease of integration, we use the JSONLead format. This format is widely recognised in the market and makes the automatic processing of sales in third-party systems easier.

Available delivery methods

You have three options for receiving sales. In every case the content of the sale in json format will be the same.

Webhook: The fastest and most direct option. Sales are sent immediately to your system's URL configured to receive them (POST request). If for security reasons you need any kind of custom header, we can add it without any problem.
SFTP/FTP: You can use our SFTP server or your own (SFTP/FTP) to receive the data. One json file will be created per sale.
Email: If you prefer, we can send you the sales in JSONLead format as the body of emails.

Example of a JSONLead sent

{
  "client": {
      "foreign_id": "1df807f0ba96f8be5529308f6667a144",
      "first_name": "John",
      "province": "Haute-Normandie",
      "postal_code": "76119",
      "phone": "600000000",
      "email": "user@mail.com",
      "custom": {
          "address": "4534 route de la mar",
          "city": "76119 - STE MARGUERITE SUR MER",
          "country": "FR"
      }
  },
  "sales_lead": {
      "origin": {
          "source": "portal_hero",
          "medium": "Ebay"
      },
      "related_urls": [
          "https://portal.com/item/1234"
      ],
      "status": "confirmed",
      "custom": {
          "account": "some_email@mail.com",
          "external_id": "1243948",
          "title": "Some pretty product",
          "created_at": "2025-01-17 10:25:22.145432",
          "update_at": "2025-01-17 18:21:11.145432",
          "amount": 1400.0,
          "shipping_amount": 0.0,
          "payment_method": "EBAY",
          "shipping": {
              "delivery_purchase_confirmed": true,
              "delivery_purchase_confirmed_ts": "2025-01-17 10:25:22.145432",
              "shipping_label_url": "https://portal-xxxx.com/tracking.pdf",
              "tracking_code": "XXXXXXXX"
          }
      },
      "foreign_id": "17-12583-30383",
      "inquiry": "[{\"created_at\": \"2022-10-31T20:03:21.360000\",\"text\": \"Te dejo mi numero de telefono 6XXXXXXXXX\"}, {\"created_at\":\"2022-10-31T19:50:55.194000\", \"text\": \"Hola!\"}]"
  },
  "version": "1.0.0"
}

* For portals that allow multiple items in the same order, the JSON elements "sales_lead.custom.external_id", "sales_lead.custom.amount" and "sales_lead.custom.title" will be a list instead of a single element. The order of the lists will be kept consistent between them.

JSONLead field details

Name	Type	Required	Description
`client.foreign_id`	string	Yes	Unique identifier of the customer.
`client.first_name`	string	Yes	Customer's name. Depending on the portal it may be a username.
`client.province`	string	No	Province of the customer's address.
`client.postal_code`	string	No	Postcode of the customer's address.
`client.phone`	string	No	Customer's phone number.
`client.email`	string	No	Customer's email.
`client.custom.address`	string	No	Customer's postal address.
`client.custom.city`	string	No	City of the customer's address.
`client.custom.country`	string	No	Country (ISO country code) of the customer's address.
`sales_lead.origin.source`	string	Yes	Origin of the sale. It will always be "portal_hero".
`sales_lead.origin.medium`	string	No	Name of the portal the sale comes from.
`sales_lead.related_urls`	array	No	Relevant URL(s). Normally the URL of the item on the portal.
`sales_lead.status`	string	Yes	Status of the sale. Currently it can be "confirmed" or "cancelled".
`sales_lead.custom.account`	string	No	Email or identifier of the account on the portal. Useful when multiple accounts are managed on the same portal, to identify the account the sale originated from.
`sales_lead.custom.external_id`	string/arraystring*	Yes	Unique identifier of the item. The same one you send us when uploading items.
`sales_lead.custom.title`	string/arraystring*	Yes	Title of the product sold.
`sales_lead.custom.created_at`	datetime	Yes	Date and time the sale was created.
`sales_lead.custom.update_at`	datetime	No	Date and time of the last update to the sale.
`sales_lead.custom.amount`	float/arrayfloat*	Yes	Total amount of the sale.
`sales_lead.custom.shipping_amount`	float	No	Amount of the shipping costs.
`sales_lead.custom.payment_method`	string	No	Payment method.
`sales_lead.custom.shipping.delivery_purchase_confirmed`	boolean	Yes	Boolean indicating whether the sale has been made. It will always be true in this case.
`sales_lead.custom.shipping.delivery_purchase_confirmed_ts`	datetime	No	Deprecated: Time the sale was created. Same value as "sales_lead.custom.created_at"
`sales_lead.custom.shipping.shipping_label_url`	string	No	URL of the shipping label. It may be a pdf or an image depending on the carrier
`sales_lead.custom.shipping.tracking_code`	string	No	Tracking number of the order with the carrier.
`sales_lead.foreign_id`	string	Yes	Unique identifier of the sale.
`sales_lead.inquiry`	array	No	Conversation held with the user on the portal.
`version`	string	Yes	Version of the jsonLead schema. Version 1.0.0 for now.

Benefits of this integration

Complete automation: Automatically process sales in your management system.
Standardisation: The JSONLead format ensures compatibility with most systems on the market.
Flexibility: Choose between webhook, SFTP or email according to what best suits your needs.

Integrate this solution into your workflow and streamline the management of your sales quickly, accurately and easily. If you need more details or technical support, get in touch! 🚀