ImobyFlowParcerias Imobiliárias
Browse the documentation
Português

Batches

Up to 500 properties or clients in one call, processed at the platform pace, with the outcome of each item.

Routes

POST/v1/properties/batch

Batch of properties

Up to 500 properties and 4 MB in one call. Each item is the PUT by code (externalRef required) — same rules, same outcomes. A malformed item comes back REJECTED and does not block the others; the same code twice in a batch is refused. Answers 202 right away and processes at the platform pace (4 items per second): 500 items take 2 to 3 minutes.

Permission: properties:writeSupports dry runSupports Idempotency-Key

Query parameters

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

Request body

itemslist of PropertyInputrequired
The items (1 to 500).

Example body

{
  "items": [
    {
      "externalRef": "AP1234",
      "title": "Apartamento 3 quartos no Bigorrilho",
      "type": "APARTAMENTO",
      "purposes": [
        "VENDA"
      ],
      "salePrice": 890000,
      "address": {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho",
        "street": "Rua Padre Anchieta",
        "number": "1500",
        "complement": "Ap 82"
      },
      "bedrooms": 3,
      "suites": 1,
      "bathrooms": 2,
      "parkingSpots": 2,
      "area": 98,
      "photos": [
        "https://www.suaimobiliaria.com.br/fotos/AP1234/1.jpg",
        "https://www.suaimobiliaria.com.br/fotos/AP1234/2.jpg"
      ]
    }
  ]
}

Response202Accepted

dataBatchCreatedrequired
The received batch.

Example

# Dry run: nothing is written. Remove ?dryRun=true to write for real.
curl -X POST 'https://api.imobyflow.com.br/v1/properties/batch?dryRun=true' \
  -H "Authorization: Bearer $IMOBYFLOW_API_KEY" \
  -H 'Accept-Language: en' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "items": [
    {
      "externalRef": "AP1234",
      "title": "Apartamento 3 quartos no Bigorrilho",
      "type": "APARTAMENTO",
      "purposes": [
        "VENDA"
      ],
      "salePrice": 890000,
      "address": {
        "cityId": "4106902",
        "neighborhoodSlug": "bigorrilho",
        "street": "Rua Padre Anchieta",
        "number": "1500",
        "complement": "Ap 82"
      },
      "bedrooms": 3,
      "suites": 1,
      "bathrooms": 2,
      "parkingSpots": 2,
      "area": 98,
      "photos": [
        "https://www.suaimobiliaria.com.br/fotos/AP1234/1.jpg",
        "https://www.suaimobiliaria.com.br/fotos/AP1234/2.jpg"
      ]
    }
  ]
}
JSON

Errors for this route

And the errors common to every route

GET/v1/properties/batch/{batchId}

Track the batch

The status, counts and each item outcome, in request order. The batch is available for 7 days.

Permission: properties:read

Path parameters

batchIdstringrequired
Batch id (b-…).

Response200OK

dataBatchrequired
The batch.

Example

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

Errors for this route

And the errors common to every route

POST/v1/leads/batch

Batch of clients

Up to 500 clients and 4 MB in one call. Each item is the PUT by code (externalRef required) — same rules, same outcomes. A malformed item comes back REJECTED and does not block the others; the same code twice in a batch is refused. Answers 202 right away and processes at the platform pace (4 items per second): 500 items take 2 to 3 minutes.

Permission: leads:writeSupports dry runSupports Idempotency-Key

Query parameters

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

Request body

itemslist of LeadInputrequired
The items (1 to 500).

Example body

{
  "items": [
    {
      "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
    }
  ]
}

Response202Accepted

dataBatchCreatedrequired
The received batch.

Example

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

GET/v1/leads/batch/{batchId}

Track the batch

The status, counts and each item outcome, in request order. The batch is available for 7 days.

Permission: leads:read

Path parameters

batchIdstringrequired
Batch id (b-…).

Response200OK

dataBatchrequired
The batch.

Example

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

Errors for this route

And the errors common to every route

Objects

BatchCreated

The received batch.

idstringrequired
Batch id (b-…).
typestringrequired
properties or leads.one of properties leads
statusstringrequired
QUEUED, or DONE when no item was valid.one of QUEUED RUNNING DONE
totalintegerrequired
Items received.
acceptedintegerrequired
Items queued for processing.
rejectedintegerrequired
Items rejected on shape (see the result).
dryRunbooleanrequired
The whole batch is a dry run.

BatchItem

One item result.

indexintegerrequired
Position in the request.
externalRefstringrequirednullable
The item's code.
outcomestringrequired
The item's outcome — the same as the PUT by code, plus PENDING (still queued) and REJECTED.
idstringrequirednullable
The property or client id.
codestringrequirednullable
The error code, when refused.
detailstringrequirednullable
Detail.
invalidParamslist of objectrequirednullable
Shape problems.
photosstringrequirednullable
The gallery (properties).

Batch

A batch, with each item outcome.

idstringrequired
Batch id.
typestringrequired
properties or leads.one of properties leads
statusstringrequired
QUEUED, RUNNING or DONE.one of QUEUED RUNNING DONE
dryRunbooleanrequired
Dry run.
totalintegerrequirednullable
Items.
processedintegerrequirednullable
Items with an outcome.
countsmaprequired
Count per outcome (CREATED, UPDATED, REJECTED…).
createdAtstringrequirednullable
When it was received.
startedAtstringrequirednullable
When it started.
finishedAtstringrequirednullable
When it finished.
resultslist of BatchItemrequired
Each item outcome, in request order.