How do I file a complaint for a lead via the API?

Via the Leadnodes API, you can file a complaint for a purchased lead in two steps: first, use the Refundable endpoint to check whether a complaint can be filed for the lead and with which reasons. Then create the complaint with the Refunds Create endpoint.

Why do I have to call the Refundable endpoint first?

Complaint reasons and complaint periods are not defined globally in Leadnodes. They depend on the specific lead:

• Lead type: Each lead type can have its own complaint reasons and its own complaint period. Some lead types cannot be subject to complaints at all.
• User (buyer): A different complaint period may be stored for individual buyers. In addition, the right to file complaints must be enabled for the user.
• System: If no period is stored for either the lead type or the user, the system’s default period applies.

The Refundable endpoint resolves these rules for the requested lead and returns exactly the complaint reasons (including their IDs) that are valid for this lead. A complaint with an ID that is not included in this list will be rejected.

Step-by-step guide

Step 1: Check whether a complaint can be filed for the lead

Send a GET request to:

https://app.leadnodes.com/api/v2/refunds/refundable/{lead_id}

Replace {lead_id} with the ID of the lead. As with all API calls, authenticate with your API token in the header Authorization: Bearer ….

Step 2: Evaluate the response

Lead is refundable ("refundable": true):

{
  "refundable": true,
  "reasons": [
    {
      "id": 17,
      "title": "Kunde nicht erreichbar",
      "description": "…",
      "is_active": 1
    },
    {
      "id": 18,
      "title": "Falsche Kontaktdaten",
      "description": "…",
      "is_active": 1
    }
  ],
  "refundable_until": "2025-12-26T13:25:08.000000Z",
  "error": null
}

• reasons: List of permitted complaint reasons. Note the id of the appropriate reason for step 3.
• refundable_until: End of the complaint period (UTC). The complaint can be created up to this point in time.

Lead is not refundable ("refundable": false):

{
  "refundable": false,
  "error": "Refund period is expired."
}

In this case, error contains the reason. Do not create a complaint then, as it would be rejected with the same error.

Step 3: Create the complaint

Send a POST request to:

https://app.leadnodes.com/api/v2/refunds/create/{lead_id}

With the following JSON body:

{
  "refund_reason_id": 17,
  "refund_comment": "Kunde war nach mehreren Versuchen nicht erreichbar."
}

• refund_reason_id (required): An ID from the reasons list from step 2.
• refund_comment (required): Your reason as free text. A meaningful comment speeds up processing.

Successful response:

{
  "message": "Refund successfully created.",
  "refund_id": 29750
}

Step 4 (optional): Query the status of the complaint

You can query the further progress at any time via GET https://app.leadnodes.com/api/v2/refunds/status/{lead_id}. The status is open (under review), accepted or declined.

How do I interpret the error messages?

Further frequently asked questions

Can I retrieve the complaint reasons once and cache them?

We advise against this. The reasons can differ per lead type and user and can be changed or deactivated by the provider at any time. Query the Refundable endpoint for the specific lead before every complaint.

When does the complaint period start?

The period starts at the time the lead is assigned (purchased) and is calculated in days. You can find the exact end of the period in the refundable_until field.

Which user role do I need for API complaints?

The API token must belong to a buyer user to whom the lead is assigned, or to a system administrator of the system. Other users receive a permission error message.

Can I withdraw or change a complaint via the API?

No. Once created, a complaint cannot be changed or deleted via the API. It is reviewed by the lead provider and accepted or declined.