BETA

Setting up a client

This is done once per client, and then you never touch it again. Two steps and one decision.

1 · you declare their record    POST /customers        → you choose their clientRef
2 · you connect their account   ← this is the fork: it depends on the portal
3 · (optional) you check         GET /customers        free

1 · The record

POST /customers with the agency's details.

What you decide here is the clientRef, and it is the decision you will use the most: it is how you tell us which client you are talking about on every subsequent call. You choose it — use the id that client already has in your system. We deliberately do not generate it, precisely so that you do not have to maintain a mapping table.

The record includes the contact details that will be published on the listing. This is not administrative: it is what the person making the enquiry sees. A record with no phone number publishes a listing with no phone number.

Their branches, once and for all

It depends on whether your client has a Mapaprop account or not. It is the only fork in this step:

If they do not — most clients. You declare their branches on the record, in branches, each one with a reference you choose (branchRef). Then each property says which one it goes out with, by sending that branchRef.

If they do — their branches already exist and they edit them in Mapaprop. Read GET /branches and declare only the link between your reference and their real id:

{ "branches": [ { "branchRef": "centro", "mapapropBranchId": 777 } ] }

The contact data of that branch comes from Mapaprop, not from what you declare. That way there are never two versions of the same phone number with one of them stale.

Your branchRef never changes, just like your clientRef and your paId. If your client comes to have a Mapaprop account later on, their branch gains an id of ours next to your reference — and your code keeps sending the same word.

It is the same mapping work as the zones, and for the same reason: the name is not enough to identify a branch.

After onboarding, each branch is managed one at a time — without resending the whole list:

You want…You call
to edit onePUT /branches/{branchRef}
to delete oneDELETE /branches/{branchRef}

Both doors work the same way for the two cases above: if your client has no Mapaprop account their record is written, and if they do have one the write goes to Mapaprop. The response tells you which of the two happened, in scope.

Adding a branch is a PUT /customers; deleting one is NOT. The record's PUT replacesbranches[] with what you send, so a branch you forget in the payload is not deleted by mistake: to delete it you have to name it with the DELETE. This is deliberate — deleting a branch that has a Mapaprop account moves its properties.

2 · Connecting their portal account — the fork

There are two ways and you do not choose between them: the portal does.

With a linkWith the credential
Who authorisesyour client, by opening a linkyou, with the credential you already obtained
You handle a credential of theirsnoyes
What you send usnothing: you request the link and pass it ontheir account's credential
PortalsZonaprop · ArgenpropArgenprop · Cabaprop · MercadoLibre

Argenprop accepts both, and the link is the recommended path: its integration credential is handed out by the portal by email to the agency, so with the link your client types it on our page and you never handle it.

Why both exist: some portals do not issue any per-account credential — the agency logs in, accepts, and the authorisation stays on their side. On those there is nothing you could store, and that is why the path is the link.

⚠️ They are not interchangeable. If you try to register a credential on a portal that goes by link, we tell you with the portal named and with the link to request it. It is not a permissions mistake on your part: it is the wrong path for that portal.

The full table of which portal goes which way is in Publication.

3 · Checking that it worked (free)

GET /customers returns the record and, beside it, the state of their connections. It costs nothing, so it is the cheap way to confirm before you start publishing.

On portals that have publication plans, your client's plans come back here too — and that is free because we bring them in the same call we use to verify that they authorised us. You do not need to request them separately.

What NOT to do during setup

  • Generating a clientRef of ours. You choose it; use yours.
  • Asking the portal for the plans. You already have them from step 3, free and with their timestamp.
  • Mapping their zones. We resolve those; you send yours.
  • Waiting for the account to be connected before you start integrating. The checker works the same without a connection, so you can get your object mapping ready before your client authorises.

If your app connects a single client

The clientRef is already fixed on our side: there is one record and you do not need to tell us which on every call. The two steps are the same.