Data Form Solution: Lead API

This page is for lead providers who work with a Data Form Solution (DFS) Brand Partner. With the partner’s key you can send each lead you generate for them straight into their DFS account, one request per lead.

1. Get a key

The Brand Partner creates the key in DFS, under Settings → Lead sources, and gives it to you. It starts with dfs_lead_. The key decides whose account each lead goes into, and it can do nothing except add leads.

Keep it secret: store it on your server, never in a web page or app. The partner can revoke it at any time; from then on every request with it is refused.

2. Send a lead

POST https://dataformsolution.com/api/v1/leads with a JSON body and these headers:

Authorization: Bearer YOUR_KEY
Content-Type: application/json
Accept: application/json

Field	Required	Notes
`first_name`	Required	Up to 255 characters.
`last_name`	Required	Up to 255 characters.
`email`	Required	The person’s own address. It is checked before the lead is accepted.
`mobile_number`	Optional	In international format, for example +61412345678.
`language`	Optional	The language DFS writes to them in, for example en-GB, de, es, fr. English when left out.
`message`	Optional	A question or note the person wrote, up to 2,000 characters. The partner sees it on the contact.
`consent.given_at`	Optional	When the person agreed to be contacted (ISO 8601).
`consent.page_url`	Optional	The page where they agreed.
`consent.text`	Optional	The words they agreed to, up to 1,000 characters.

Example:

curl -X POST https://dataformsolution.com/api/v1/leads \
  -H "Authorization: Bearer dfs_lead_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "mobile_number": "+61412345678",
    "language": "en-GB",
    "message": "I would like to know more about X39.",
    "consent": {
      "given_at": "2026-10-25T09:30:00Z",
      "page_url": "https://provider.example/lifewave-offer",
      "text": "Yes, contact me about LifeWave products."
    }
  }'

3. Responses

201 Created	The lead is in the partner’s DFS account. The body is {"status": "created", "contact_id": 123}.
200 OK	The person is already one of the partner’s contacts. Nothing was changed and no email was sent. The body is {"status": "existing", "contact_id": 123}.
401 Unauthorized	The key is missing, wrong or has been revoked.
403 Forbidden	The partner’s DFS account cannot receive leads right now, for example because their DFS Pro plan has ended.
422 Unprocessable	The lead is not valid. "errors" lists each field. When the email address does not exist or is a throwaway address, a likely correction may be given in "email_suggestion".
429 Too Many Requests	Too many requests: at most 60 a minute, and 200 new leads per key in 24 hours. "retry_after" says how many seconds to wait.

Sending the same person again is safe: you get 200 and nothing happens twice.

4. What happens to a lead

DFS checks the email address. One that does not exist or is a throwaway address is refused.
DFS emails the person in their language and asks them to confirm they want to hear from the partner. Nothing else is sent to them until they do. Whatever you send in consent is kept as a record, but DFS still asks the person itself.
The partner sees the new lead in DFS and in the DFS Companion app.
Someone who is already one of the partner’s contacts is left as they are.

5. Rules

Send only people who asked to be contacted about what this partner offers. Never send bought, rented or scraped lists.
One key per provider, and per partner. Do not share a key between partners.
DFS may revoke a key that sends addresses that bounce or people who complain.

Help

Email [email protected] with the time of the request and the response you got. Never send us the key itself.