Managing Leads

The Lead Management API provides functionality to retrieve and analyse lead data, enabling developers to access detailed information about specific leads or aggregated lead data for suppliers.

Accepting a lead turns the lead into a purchaser.

Endpoints

Get Lead by ID

Retrieve detailed information about a specific lead using its unique GUID (Identified by a 36-character string). It provides nested details about the associated retailer, supplier, and connection request.

Endpoint:

GET /v1/leads/{id}

Description:

This endpoint returns the full details of a lead, including fields such as status, chargeable, isApproved, createdAt, and more. It also provides nested details about the associated retailer, supplier, and connection request.

Path Parameter:

id (string, required): The unique identifier of the lead (GUID format).

Example Request:

curl -X GET "https://api.ordermentum.com/v1/leads/651bdbbe-5387-4741-bcb6-6e4ccceeb19c" \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response (200 OK):

{
  "id": "651bdbbe-5387-4741-bcb6-6e4ccceeb19c",
  "status": "unprocessed",
  "chargeable": false,
  "isApproved": false,
  "isRejected": false,
  "isActivated": false,
  "parsedStatus": "Unprocessed",
  "retailerId": "fb85475b-1d8e-45d0-99e1-ee935e4d0df3",
  "supplierId": "4fe760f3-e7f8-4044-bc42-fcbb8cf4e610",
  "connectionRequestId": "a4177710-5661-4089-9df1-afddf5483ff7",
  "actionedBy": "de940c29-bd91-46c5-9176-dffd09813703",
  "actionedByUser": "John Doe",
  "actionedAt": null,
  "responses": {},
  "updatedAt": "2023-12-06T23:08:30.625Z",
  "createdAt": "2023-12-06T23:08:30.625Z",
  "assignedUserId": null,
  "expiresAt": null,
  "assignedUser": "",
  "connectionRequest": {
    "id": "a4177710-5661-4089-9df1-afddf5483ff7",
    "createdBy": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "0458253698"
    },
    "status": "Request sent",
    "supplier": {
      "tradingName": "Example Supplier"
    },
    "retailer": {
      "tradingName": "Example Retailer",
      "address": {
        "formatted": "123 Main St, Sydney NSW 2000, Australia"
      },
      "phone": "0298765432"
    },
    "isApproved": true,
    "isRejected": false,
    "chargeable": null,
    "createdAt": "2023-12-06T23:08:30.583Z",
    "updatedAt": "2023-12-06T23:08:30.598Z"
  },
  "retailer": {
    "id": "fb85475b-1d8e-45d0-99e1-ee935e4d0df3",
    "name": "Example Retailer",
    "legalName": "Example Retailer Pty Ltd",
    "tradingName": "Example Retailer",
    "email": "[email protected]",
    "phone": "0298765432",
    "address": {
      "formatted": "123 Main St, Sydney NSW 2000, Australia"
    }
  },
  "purchaserId": null,
  "purchaser": null,
  "parsedSource": "Ordermentum app",
  "supplierGrowthEngineActive": true,
  "inDeliveryArea": false,
  "profileId": "048edd6b-f5aa-494f-b848-1275a2e97271",
  "profileName": "Example Profile",
  "userId": "de940c29-bd91-46c5-9176-dffd09813703",
  "warning": true,
  "expired": false,
  "deletedAt": null,
  "creatorName": "John Doe",
  "creatorEmail": "[email protected]",
  "customerPhone": "0298765432",
  "customerEmail": "[email protected]",
  "customerPostcode": "2000",
  "purchaserTrading": false
}

Key Fields:

status: The current status of the lead (e.g., unprocessed).
chargeable: Indicates whether the lead is chargeable.
isApproved: Indicates whether the lead has been approved.
createdAt: The timestamp when the lead was created.
connectionRequest: Contains details about the connection request, including the creator, supplier, and retailer information.
retailer: Provides details about the retailer associated with the lead, including name, contact information, and address.

Error Responses:

400 Bad Request: Invalid data provided (e.g., malformed ID).
403 Forbidden: No access to the retailer associated with the lead.

Default: An error message with details about the issue.