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 one | PUT /branches/{branchRef} |
| to delete one | DELETE /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 link | With the credential | |
|---|---|---|
| Who authorises | your client, by opening a link | you, with the credential you already obtained |
| You handle a credential of theirs | no | yes |
| What you send us | nothing: you request the link and pass it on | their account's credential |
| Portals | Zonaprop · Argenprop | Argenprop · 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
clientRefof 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.
Related
- Publishing a listing — the next step
- Clients — the four record methods, including updating it when a contact detail changes
- Branches — the three methods: list them, edit one and delete one
- Zonaprop · Argenprop — the sections for the two portals that go by link, each with what is specific to it
- Checking and disconnecting — and taking things down, for the difference between disconnecting and deleting