Concepts
External ID
Use your CRM IDs instead of Rentix internal IDs
External ID is the recommended approach for integration. You don't need to store Rentix IDs in your database. Use object IDs from your CRM — the API will find the corresponding records automatically.
The Problem Without External ID
A typical integration without external ID requires an additional mapping table:
Your CRM Mapping Table Rentix
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ ID: APT-001 │ ──────────► │ APT-001 → 42 │ ───► │ ID: 42 │
│ ID: APT-002 │ │ APT-002 → 43 │ │ ID: 43 │
└─────────────┘ └──────────────────┘ └─────────────┘
For each update you need to:
- Find the mapping in your database
- Get the Rentix ID
- Send the request with that ID
The Solution With External ID
With external ID, no mapping is needed — the API handles it:
Your CRM Rentix
┌─────────────┐ ┌─────────────────────┐
│ ID: APT-001 │ ───── externalId: "APT-001" ────────► │ ID: 42 │
│ ID: APT-002 │ │ externalId: APT-001 │
└─────────────┘ └─────────────────────┘
When updating:
- Send a request with
externalId: "APT-001" - The API finds listing #42 automatically
How to Use
On Creation
Pass externalId — your ID from the CRM:
{
"externalId": "APT-001",
"announcementType": "rent",
"propertyType": "residential",
"propertySecondaryType": "apartment",
"announcementValue": 500
}
On Update
Same externalId — the API finds the existing listing:
{
"externalId": "APT-001",
"announcementValue": 600
}
On Retrieval
Use the endpoint with /external/:
// By external ID
const response = await fetch(
'https://crm.rentix.md/api/v1/listings/external/APT-001',
{ headers: { 'Authorization': 'ApiKey YOUR_API_KEY' } }
);
const listing = await response.json();
console.log(listing.id); // 42 (internal ID)
console.log(listing.externalId); // "APT-001" (your ID)
curl https://crm.rentix.md/api/v1/listings/external/APT-001 \
-H "Authorization: ApiKey YOUR_API_KEY"
$ch = curl_init('https://crm.rentix.md/api/v1/listings/external/APT-001');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: ApiKey YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$listing = json_decode($response, true);
Usage Rules
| Rule | Description |
|---|---|
| Maximum length | 255 characters |
| Allowed characters | Letters, numbers, hyphens, underscores |
| Uniqueness | Within agency and resource type |
One
externalId can belong to a listing, and the same ID can belong to a media file. There won't be a conflict because they're different resource types.Supported Resources
External ID works for all main resources:
| Resource | Example Endpoint |
|---|---|
| Listings | GET /listings/external/{externalId} |
| Users | GET /users/external/{externalId} |
| Media | GET /media/external/{externalId} |
Linking to Existing Objects
If an object was created without externalId, you can link it later:
// Link external ID to listing #42
await fetch('https://crm.rentix.md/api/v1/listings/42/link', {
method: 'POST',
headers: {
'Authorization': 'ApiKey YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ externalId: 'APT-001' })
});
curl -X POST https://crm.rentix.md/api/v1/listings/42/link \
-H "Authorization: ApiKey YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "externalId": "APT-001" }'
$ch = curl_init('https://crm.rentix.md/api/v1/listings/42/link');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['externalId' => 'APT-001']));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: ApiKey YOUR_API_KEY',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_exec($ch);
To unlink an external ID:
curl -X DELETE https://crm.rentix.md/api/v1/listings/42/link \
-H "Authorization: ApiKey YOUR_API_KEY"
Common Errors
| Error | Cause | Solution |
|---|---|---|
External ID already linked | ID is already used by another object | Use a unique ID |
Cannot provide both id and externalId | Both parameters were passed | Use only one |