ImobyFlowParcerias Imobiliárias
Browse the documentation
Português

Clients

The account's clients, with the search profile that drives recommendations: read, sync by your system's code, move through the funnel, archive and log interactions.

Routes

GET/v1/leads

List clients

The account's clients, newest first, with filters.

Permission: leads:read

Query parameters

limitinteger
Items per page: 1 to 100 (default 50).
cursorstring
The nextCursor from the previous page. The list is over when it comes back null. It is only valid for this route and this account.
statestring
ACTIVE (default), ARCHIVED or DELETED.one of ACTIVE ARCHIVED DELETED
statusstring
Stage.one of NEW ATTENDING PROPOSAL WON LOST
ownerAccountIdstring
Only one broker's items.
updatedSincestring
Only what changed since this date/time (ISO 8601, UTC).
radarstring
pending = only items with recommendation pending items; ready = only ready items.one of pending ready

Response200OK

datalist of Leadrequired
The clients.
nextCursorstringrequirednullable
Next page cursor (null = done).

Example

curl -X GET 'https://api.imobyflow.com.br/v1/leads' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en'

Errors for this route

And the errors common to every route

GET/v1/leads/{leadId}

One client

The client, with the search profile and recommendation status.

Permission: leads:read

Path parameters

leadIdstringrequired
Client id (lead-…).

Response200OK

dataLeadrequired
The client.

Example

curl -X GET 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en'

Errors for this route

And the errors common to every route

GET/v1/leads/by-ref/{ref}

One client by your code

The client by your system's code.

Permission: leads:read

Path parameters

refstringrequired
The client's code in your system (up to 80 characters).

Response200OK

dataLeadrequired
The client.

Example

curl -X GET 'https://api.imobyflow.com.br/v1/leads/by-ref/CLI-889' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en'

Errors for this route

And the errors common to every route

PUT/v1/leads/by-ref/{ref}

Create, update or link by your code

Creates the client (201), updates it (200) — or LINKS it: the code is new but the person is already here by phone or e-mail (from a portal, a spreadsheet); the code now points to them (LINKED), without a second client. On creation, consentGiven: true is required.

Permission: leads:writeSupports dry runSupports Idempotency-Key

Path parameters

refstringrequired
The client's code in your system (up to 80 characters).

Query parameters

dryRunboolean
true = dry run: validates and says what would happen, without writing anything.

Request body

externalRefstring
The client's code in your system (POST only).
namestring
Name. Required on creation.
phoneslist of PhoneInput
Up to 5 phones. On creation, a phone or an e-mail.
emailstringnullable
E-mail.
statusstring
Funnel stage.one of NEW ATTENDING PROPOSAL WON LOST
notesstring
Notes.
preApprovedboolean
Pre-approved credit.
sharedToNetworkboolean
The profile may receive partner properties.
interestInterestInput
Search profile.
ownerAccountIdstring
The responsible broker, by id.
ownerEmailstring
The responsible broker, by e-mail — the way your system knows them. Without one, the agency's distribution rule applies.
lastActivityAtstring
The last activity in YOUR system. It only moves forward. More than 60 days ago on creation = the client is created archived (historical base).
consentGivenboolean
Must be true on creation: the agency declares it has the legal basis to process the data (API Terms).

Example body

{
  "name": "Carlos Pereira",
  "phones": [
    {
      "number": "(41) 99999-8888",
      "isWhatsApp": true
    }
  ],
  "email": "carlos@example.com",
  "status": "ATTENDING",
  "ownerEmail": "marina@suaimobiliaria.com.br",
  "interest": {
    "purposes": [
      "VENDA"
    ],
    "propertyTypes": [
      "APARTAMENTO"
    ],
    "locations": [
      {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho"
      }
    ],
    "salePriceMax": 950000,
    "bedrooms": 3
  },
  "lastActivityAt": "2026-10-02T15:00:00Z",
  "consentGiven": true
}

Response200OK201 when it creates.

dataLeadrequired
The object as it now stands.
resultLeadWriteResultrequired
The outcome.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X PUT 'https://api.imobyflow.com.br/v1/leads/by-ref/CLI-889?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "name": "Carlos Pereira",
  "phones": [
    {
      "number": "(41) 99999-8888",
      "isWhatsApp": true
    }
  ],
  "email": "carlos@example.com",
  "status": "ATTENDING",
  "ownerEmail": "marina@suaimobiliaria.com.br",
  "interest": {
    "purposes": [
      "VENDA"
    ],
    "propertyTypes": [
      "APARTAMENTO"
    ],
    "locations": [
      {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho"
      }
    ],
    "salePriceMax": 950000,
    "bedrooms": 3
  },
  "lastActivityAt": "2026-10-02T15:00:00Z",
  "consentGiven": true
}
JSON

Errors for this route

And the errors common to every route

POST/v1/leads

Create a client

Creates a client. Minimum: name, a phone or e-mail and consentGiven: true. An existing contact → 409 with the id. Without an owner, the agency's distribution rule applies.

Permission: leads:writeSupports dry runSupports Idempotency-Key

Query parameters

dryRunboolean
true = dry run: validates and says what would happen, without writing anything.

Request body

externalRefstring
The client's code in your system (POST only).
namestring
Name. Required on creation.
phoneslist of PhoneInput
Up to 5 phones. On creation, a phone or an e-mail.
emailstringnullable
E-mail.
statusstring
Funnel stage.one of NEW ATTENDING PROPOSAL WON LOST
notesstring
Notes.
preApprovedboolean
Pre-approved credit.
sharedToNetworkboolean
The profile may receive partner properties.
interestInterestInput
Search profile.
ownerAccountIdstring
The responsible broker, by id.
ownerEmailstring
The responsible broker, by e-mail — the way your system knows them. Without one, the agency's distribution rule applies.
lastActivityAtstring
The last activity in YOUR system. It only moves forward. More than 60 days ago on creation = the client is created archived (historical base).
consentGivenboolean
Must be true on creation: the agency declares it has the legal basis to process the data (API Terms).

Example body

{
  "externalRef": "CLI-889",
  "name": "Carlos Pereira",
  "phones": [
    {
      "number": "(41) 99999-8888",
      "isWhatsApp": true
    }
  ],
  "email": "carlos@example.com",
  "status": "ATTENDING",
  "ownerEmail": "marina@suaimobiliaria.com.br",
  "interest": {
    "purposes": [
      "VENDA"
    ],
    "propertyTypes": [
      "APARTAMENTO"
    ],
    "locations": [
      {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho"
      }
    ],
    "salePriceMax": 950000,
    "bedrooms": 3
  },
  "lastActivityAt": "2026-10-02T15:00:00Z",
  "consentGiven": true
}

Response201Created

dataLeadrequired
The object as it now stands.
resultLeadWriteResultrequired
The outcome.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X POST 'https://api.imobyflow.com.br/v1/leads?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "externalRef": "CLI-889",
  "name": "Carlos Pereira",
  "phones": [
    {
      "number": "(41) 99999-8888",
      "isWhatsApp": true
    }
  ],
  "email": "carlos@example.com",
  "status": "ATTENDING",
  "ownerEmail": "marina@suaimobiliaria.com.br",
  "interest": {
    "purposes": [
      "VENDA"
    ],
    "propertyTypes": [
      "APARTAMENTO"
    ],
    "locations": [
      {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho"
      }
    ],
    "salePriceMax": 950000,
    "bedrooms": 3
  },
  "lastActivityAt": "2026-10-02T15:00:00Z",
  "consentGiven": true
}
JSON

Errors for this route

And the errors common to every route

PATCH/v1/leads/{leadId}

Partially update a client

Changes only what is sent. Changing the stage is logged but does not count as activity — for that send lastActivityAt or log an interaction.

Permission: leads:writeSupports dry runSupports Idempotency-Key

Path parameters

leadIdstringrequired
Client id (lead-…).

Query parameters

dryRunboolean
true = dry run: validates and says what would happen, without writing anything.

Request body

externalRefstring
The client's code in your system (POST only).
namestring
Name. Required on creation.
phoneslist of PhoneInput
Up to 5 phones. On creation, a phone or an e-mail.
emailstringnullable
E-mail.
statusstring
Funnel stage.one of NEW ATTENDING PROPOSAL WON LOST
notesstring
Notes.
preApprovedboolean
Pre-approved credit.
sharedToNetworkboolean
The profile may receive partner properties.
interestInterestInput
Search profile.
ownerAccountIdstring
The responsible broker, by id.
ownerEmailstring
The responsible broker, by e-mail — the way your system knows them. Without one, the agency's distribution rule applies.
lastActivityAtstring
The last activity in YOUR system. It only moves forward. More than 60 days ago on creation = the client is created archived (historical base).
consentGivenboolean
Must be true on creation: the agency declares it has the legal basis to process the data (API Terms).

Example body

{
  "status": "PROPOSAL",
  "lastActivityAt": "2026-10-02T15:00:00Z"
}

Response200OK

dataLeadrequired
The object as it now stands.
resultLeadWriteResultrequired
The outcome.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X PATCH 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "status": "PROPOSAL",
  "lastActivityAt": "2026-10-02T15:00:00Z"
}
JSON

Errors for this route

And the errors common to every route

POST/v1/leads/{leadId}/state

Archive or reactivate

ARCHIVED archives; ACTIVE reactivates. The same function as the dashboard.

Permission: leads:writeSupports dry runSupports Idempotency-Key

Path parameters

leadIdstringrequired
Client id (lead-…).

Query parameters

dryRunboolean
true = dry run: validates and says what would happen, without writing anything.

Request body

statestringrequired
The state.one of ACTIVE ARCHIVED

Example body

{
  "state": "ARCHIVED"
}

Response200OK

dataLeadrequired
The object as it now stands.
resultLeadWriteResultrequired
The outcome.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X POST 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f/state?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "state": "ARCHIVED"
}
JSON

Errors for this route

And the errors common to every route

POST/v1/leads/{leadId}/interactions

Log an interaction

A contact, visit, proposal or note made in YOUR system, with its date. It counts as activity (the client is not archived for inactivity).

Permission: leads:writeSupports dry runSupports Idempotency-Key

Path parameters

leadIdstringrequired
Client id (lead-…).

Query parameters

dryRunboolean
true = dry run: validates and says what would happen, without writing anything.

Request body

typestringrequired
CONTACT, VISIT, PROPOSAL or NOTE.one of CONTACT VISIT PROPOSAL NOTE
notestring
Note.
atstring
When it happened (default: now).

Example body

{
  "type": "VISIT",
  "note": "Visitou o AP1234 com a esposa.",
  "at": "2026-10-02T15:00:00Z"
}

Response200OK

dataLeadrequired
The object as it now stands.
resultLeadWriteResultrequired
The outcome.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X POST 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f/interactions?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "type": "VISIT",
  "note": "Visitou o AP1234 com a esposa.",
  "at": "2026-10-02T15:00:00Z"
}
JSON

Errors for this route

And the errors common to every route

DELETE/v1/leads/{leadId}

Move to the trash

A 30-day trash; cancels the client's open partnerships, as the dashboard does. The same shrink guard as properties.

Permission: leads:writeSupports dry runSupports Idempotency-Key

Path parameters

leadIdstringrequired
Client id (lead-…).

Query parameters

dryRunboolean
true = dry run: validates and says what would happen, without writing anything.

Response200OK

dataLeadrequired
The object as it now stands.
resultLeadWriteResultrequired
The outcome.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X DELETE 'https://api.imobyflow.com.br/v1/leads/lead-7c2e9a1b3d5f?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)"

Errors for this route

And the errors common to every route

Objects

Phone

A phone number.

numberstringrequired
Digits only, with area code (10 to 13).
isWhatsAppbooleanrequired
Is WhatsApp.
labelstringrequirednullable
Free label (mobile, work…).

Location

A region of interest.

cityIdstringrequirednullable
IBGE code.
citySlugstringrequirednullable
City identifier.
cityNamestringrequirednullable
City name.
ufstringrequirednullable
State.
neighborhoodSlugstringrequirednullable
Catalog neighborhood (null = the whole city).
neighborhoodNamestringrequirednullable
Neighborhood name.
preferencestringrequired
PREFERRED or ACCEPTABLE — it weighs on the recommendation score.one of PREFERRED ACCEPTABLE

Interest

The search profile — it is what drives recommendations.

purposeslist of stringrequired
Purposes: VENDA (sale), LOCACAO (rent) or both.one of VENDA LOCACAO
propertyTypeslist of stringrequired
Property types wanted.one of APARTAMENTO CASA_RUA CASA_CONDOMINIO CASA_VILA STUDIO FLAT COBERTURA SALA_COMERCIAL LOJA_PONTO GALPAO PREDIO TERRENO_RUA TERRENO_CONDOMINIO CHACARA_SITIO FAZENDA
locationslist of Locationrequired
Regions of interest.
similarNeighborhoodsbooleanrequired
Accepts neighborhoods similar to the chosen ones.
salePriceMinnumberrequirednullable
Purchase: minimum, in BRL.
salePriceMaxnumberrequirednullable
Purchase: maximum, in BRL.
rentPriceMinnumberrequirednullable
Rent: minimum, in BRL.
rentPriceMaxnumberrequirednullable
Rent: maximum, in BRL.
bedroomsintegerrequirednullable
Minimum bedrooms.
bathroomsintegerrequirednullable
Minimum bathrooms.
parkingSpotsintegerrequirednullable
Minimum parking spots.
areaMinnumberrequirednullable
Minimum area, in m².

LeadRadar

The client's status in recommendations.

eligiblebooleanrequired
Receives recommendations right now (active and with no pending item).
pendinglist of stringrequired
What is missing in the search profile.one of PURPOSE_MISSING PROPERTY_TYPES_MISSING CITY_MISSING CITY_NOT_IN_CATALOG BUDGET_MISSING SALE_BUDGET_MISSING RENT_BUDGET_MISSING OTHER
labelslist of stringrequired
The same pending items, spelled out.

Lead

A client of the account. Name, phone and e-mail are personal data — the agency is the controller.

idstringrequired
Client id.
externalRefstringrequirednullable
The client's code in YOUR system.
ownerAccountIdstringrequirednullable
The responsible broker (or the agency itself).
statestringrequired
ACTIVE, ARCHIVED or DELETED (trash).one of ACTIVE ARCHIVED DELETED
statusstringrequirednullable
Funnel stage.one of NEW ATTENDING PROPOSAL WON LOST
namestringrequirednullable
Name.
phoneslist of Phonerequired
Phones.
emailstringrequirednullable
E-mail.
sourcestringrequired
Where it came from: MANUAL, IMPORT_CSV, EMAIL, WEBHOOK, META_ADS, PORTAL_API, CRM_API (through the API)…
sourceDetailstringrequirednullable
Source detail (the portal, the system name).
sourcePropertyIdstringrequirednullable
The property that brought the client, if any.
preApprovedbooleanrequired
Pre-approved credit.
sharedToNetworkbooleanrequired
The profile (without name or contact) may receive partner properties.
notesstringrequirednullable
Notes.
interestInterestrequired
Search profile.
radarLeadRadarrequired
Recommendation status.
lastActivityAtstringrequirednullable
Last activity — moves with the date your system sends and with interactions, never with sync itself.
archivedAtstringrequirednullable
When it was archived.
archivedReasonstringrequirednullable
Why it was archived (MANUAL, INACTIVITY, IMPORT…).
deletedAtstringrequirednullable
When it was moved to the trash.
createdAtstringrequired
When it was created (UTC).
updatedAtstringrequired
Last change (UTC).

PhoneInput

A phone. A plain string with the number is also accepted.

numberstring
With area code; only digits count.
isWhatsAppboolean
Is WhatsApp (default: yes).
labelstring
Free label.

LocationInput

A region of interest.

cityIdstring
IBGE code.
cityNamestring
City name (with uf).
ufstring
State.
neighborhoodSlugstring
Catalog neighborhood.
neighborhoodNamestring
Neighborhood as text. Market areas ("Ecoville") expand into the catalog neighborhoods they cover.
preferencestring
PREFERRED (default) or ACCEPTABLE.one of PREFERRED ACCEPTABLE

InterestInput

The search profile. Merged field by field: sending only the maximum does not erase the regions.

purposeslist of string
Purposes.one of VENDA LOCACAO
propertyTypeslist of string
Types wanted.one of APARTAMENTO CASA_RUA CASA_CONDOMINIO CASA_VILA STUDIO FLAT COBERTURA SALA_COMERCIAL LOJA_PONTO GALPAO PREDIO TERRENO_RUA TERRENO_CONDOMINIO CHACARA_SITIO FAZENDA
locationslist of LocationInput
Regions (up to 20). Send the whole list when you send it.
similarNeighborhoodsboolean
Accepts similar neighborhoods.
salePriceMinnumbernullable
Purchase: minimum.
salePriceMaxnumbernullable
Purchase: maximum. Below the minimum is refused.
rentPriceMinnumbernullable
Rent: minimum.
rentPriceMaxnumbernullable
Rent: maximum. Below the minimum is refused.
bedroomsintegernullable
Minimum bedrooms.
bathroomsintegernullable
Minimum bathrooms.
parkingSpotsintegernullable
Minimum parking spots.
areaMinnumbernullable
Minimum area, in m².

LeadInput

The fields the API accepts for a client. Unknown fields are an error; absent fields are kept.

externalRefstring
The client's code in your system (POST only).
namestring
Name. Required on creation.
phoneslist of PhoneInput
Up to 5 phones. On creation, a phone or an e-mail.
emailstringnullable
E-mail.
statusstring
Funnel stage.one of NEW ATTENDING PROPOSAL WON LOST
notesstring
Notes.
preApprovedboolean
Pre-approved credit.
sharedToNetworkboolean
The profile may receive partner properties.
interestInterestInput
Search profile.
ownerAccountIdstring
The responsible broker, by id.
ownerEmailstring
The responsible broker, by e-mail — the way your system knows them. Without one, the agency's distribution rule applies.
lastActivityAtstring
The last activity in YOUR system. It only moves forward. More than 60 days ago on creation = the client is created archived (historical base).
consentGivenboolean
Must be true on creation: the agency declares it has the legal basis to process the data (API Terms).

LeadWriteResult

The write outcome.

outcomestringrequired
What happened: CREATED, UPDATED, UNCHANGED, LINKED (the code now points to a client that already existed by contact), ARCHIVED (created archived, historical base), STATE_SET (archived or reactivated), ADDED (interaction logged), DELETED, ALREADY_DELETED.
dryRunbooleanrequired
It was a dry run — nothing was written.
interactionobject
The logged interaction (only in POST /leads/{leadId}/interactions).
interaction.idstringrequired
Record id.
interaction.typestringrequired
Type.
interaction.notestringrequirednullable
Note.
interaction.atstringrequirednullable
When it happened.