Leads API

Send leads into OctoFlow from any tool

A lead source like LeadNavigator, a web form, or a CRM can post leads to OctoFlow. Each lead lands as a contact under its company on the mind map you name, and the account owner gets an email with a link to the new contact. Available on Pro.

1Create an API key

In the web app open Settings, then Integrations, then Leads API. Give the key a name such as LeadNavigator and click Create key. Copy it right away because it is shown only once. You can hold up to five keys and revoke any of them there at any time.

2Post leads to the endpoint

Send a POST request with the key as a bearer token and a JSON body.

POST https://us-central1-octoflow-543dd.cloudfunctions.net/leads
Authorization: Bearer ofk_your_key_here
Content-Type: application/json

One lead per request looks like this.

{
  "map": "ERP Prospects",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@acme.com",
  "phone": "303 555 0100",
  "company": "Acme Manufacturing",
  "title": "VP Operations",
  "website": "acme.com",
  "city": "Denver",
  "state": "CO",
  "source": "ERP search",
  "notes": "Downloaded the buyer guide on Tuesday"
}

Or send several at once, up to 100 per request. Each lead names its own map, so one call can feed two maps.

{
  "leads": [
    { "map": "Website Visitors", "firstName": "Sam", "lastName": "Lee", "email": "sam@northwind.com", "company": "Northwind" },
    { "map": "Website Visitors", "firstName": "Ana", "lastName": "Ruiz", "email": "ana@contoso.com", "company": "Contoso", "phone": "720 555 0199" }
  ]
}

A complete example from the command line.

curl -X POST https://us-central1-octoflow-543dd.cloudfunctions.net/leads \
  -H "Authorization: Bearer ofk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "map": "ERP Prospects", "firstName": "Jane", "lastName": "Doe", "email": "jane@acme.com", "phone": "303 555 0100", "company": "Acme Manufacturing", "title": "VP Operations", "website": "acme.com", "city": "Denver", "state": "CO", "source": "ERP search", "notes": "Downloaded the buyer guide on Tuesday" }'

3Fields

Every field is a string. Unknown fields are ignored. Field names are read as written here.

Field	Needed	What it does
`map`	Recommended	The name of the mind map the lead goes on. OctoFlow creates the map on the first lead with that name. Leave it out and the lead lands on a map called Leads. An account can hold up to 10 maps.
`firstName, lastName`	One of these or email	The person's name. You can send name instead as one field.
`email`	Recommended	The work email. Used to spot a lead already on that map so nobody is added twice.
`phone`	Optional	Their direct number. Shown on the contact card with one tap to call.
`company`	Recommended	The company. It becomes the account bubble the person sits under, matched by name or by website. Without it OctoFlow uses the email's domain.
`title`	Optional	Their job title. Shown under the name.
`website`	Optional	The company website, like acme.com. Helps match the company to an account already on the map.
`linkedin`	Optional	The LinkedIn profile URL.
`city, state`	Optional	Where the person is. Puts them on OctoMaps.
`source`	Recommended	How the lead was found, in plain words, like a campaign or the page they visited. The notification email shows it in its own column, so make it specific.
`notes`	Optional	Anything the rep should know. Included in the notification email and kept on the contact.

4What comes back

A 200 response lists every lead with a status. created means a new contact. updated means the email was already on that map and the empty details were filled in. existing means it was already there with nothing to add. skipped carries a reason, such as a lead with no email and no name, or an account already holding 10 maps.

{
  "ok": true,
  "received": 1,
  "created": 1,
  "updated": 0,
  "existing": 0,
  "skipped": 0,
  "results": [
    {
      "email": "jane@acme.com",
      "name": "Jane Doe",
      "company": "Acme Manufacturing",
      "map": "ERP Prospects",
      "mapId": "custom_k3j9x2a",
      "accountId": "1f2e3d4c",
      "contactId": "9a8b7c6d",
      "status": "created",
      "url": "https://app.octoflowus.com/workspace/mindmap?map=custom_k3j9x2a&node=9a8b7c6d"
    }
  ]
}

Errors come back as JSON with an error code.

Status	Code	Meaning
401	`invalid_key`	The key is missing, wrong, or was revoked.
402	`plan_required`	The account's Pro plan is not active.
400	`no_leads`	The body had no lead in it.
413	`too_many`	More than 100 leads in one request.

5What the rep sees

The moment a lead lands, the account owner gets an email listing who arrived, their company and contact details, any notes, and a link that opens the contact on the mind map. The dashboard shows the new names too, and the contact appears on the map in the web app and the extension like any other. Email alerts can be turned off per key in Settings.

Looking for the HubSpot connection or website visit tracking? See Integrations. Questions about the API go to grant@octoflowus.com.