Transactions
Get Transaction
- Endpoint:
GET /transactions/{id}
- Allowed for:
Users that are involved in the transaction, the user assigned or admins.
Curl example :
$ curl -X GET 'http://api-v2.mycrm.com/transactions'
- JSON response example:
{
"transaction" : {
"id": "1",
"date": "2012-01-01",
"reference": "AVC123",
"type": "direct",
}
}
Get Transactions
- Endpoint:
GET /transactions
| Name | Type | Comment |
|---|---|---|
| id | int | ID of transaction |
| property or mls_property | Property details | |
| user | array | User details |
| lead | array | Lead details |
| landlord | array | Landlord details |
| reference | string | reference of transaction |
| type | string | type of transaction (direct, indirect) |
| created_by | string | user/system that has created the transaction |
| developer_noc | boolean | developer NOC |
| status | string | transaction status |
| reason | string | comment about the status |
| negotiated_price | integer | The price negotiated during the transaction |
| contract_signed_at | date | Date of the transaction deal |
| contributors | array | List of contributors |
| notes | array | List of notes |
| documents | array | List of documents |
| acl_requests | array | List of ACL requests |
| resource_accesses | array | List of resource accesses |
- Fields sent for
rent:
| Name | Type | Comment |
|---|---|---|
| contract_start_at | date | date when the contract starts |
| contract_end_at | date | date when the contract ends |
| deposit | array | Commission object |
| owner_commission | array | Commission object |
| tenant_commission | array | Commission object |
| total_negotiated_price | int | price on the period * the rent period |
| rent_period | string | Rent period |
| gross_price | string | Gross price of the transaction |
- Fields sent for
sale:
| Name | Type | Comment |
|---|---|---|
| down_payment | array | Commission object |
| buyer_commission | array | Commission object |
| seller_commission | array | Commission object |
| date | date | date of the transfer |
| gross_price | array | gross price |
- Details of ACL requests:
| Name | Type | Comment |
|---|---|---|
| id | int | ID of the transaction |
| transaction | array | transaction array with the ID of the transaction |
| requester | array | user array with the ID of the requester |
| receiver | array | user array with the ID of the receiver |
| resource | array | type and id of the resource linked |
| comment | string | comment in the request |
| status | string | status of the request (pending, accepted or rejected) |
| created_at | date | date of the creation |
| updated_at | date | date of the update |
- Details of ACL resource accesses:
| Name | Type | Comment |
|---|---|---|
| id | int | ID of the transaction |
| transaction | array | transaction array with the ID of the transaction |
| resource | array | type and id of the resource linked |
| status | string | status of the request (pending, linked, granted or denied) |
| created_at | date | date of the creation |
| updated_at | date | date of the update |
- Allowed for:
Users that are involved in the transaction, the user assigned or admins.
- JSON response:
This endpoint will return a list of Transaction.
- JSON response example:
{
"transaction": [
{
"id": 223443,
"reference": "123ABC",
...
},
{
"id": 8678530,
"reference": "456ABC",
...
}
]
}
- Filters :
| Name | Comment | Value |
|---|---|---|
| reference | filter by poperty/transaction reference | ex: 'illusion-1' |
| type | filter by transaction type | direct or indirect |
| involved | Array of involved people | ex: user:1,client:1,landlord:1, lead:1 |
| offering_type | filter by financial type of transaction | rent or sale |
| contract_signed_date_from | Filter by contract date (rent and sale) | date format like 2017-01-01 |
| contract_signed_date_to | Filter by contract date (rent and sale) | date format like 2017-01-01 |
| contract_start_date_from | Filter by contract validity date (rent only) | date format like 2017-01-01 |
| contract_start_date_to | Filter by contract validity date (rent only) | date format like 2017-01-01 |
| contract_end_date_from | Filter by contract validity date (rent only) | date format like 2017-01-01 |
| contract_end_date_to | Filter by contract validity date (rent only) | date format like 2017-01-01 |
| transfer_date_from | Filter by transfer date (sale only) | date format like 2017-01-01 |
| transfer_date_to | Filter by transfer date (sale only) | date format like 2017-01-01 |
| created_date_from | Filter by creation date | date format like 2017-01-01 |
| created_date_to | Filter by creation date | date format like 2017-01-01 |
| locations | An array of locations | a location path like are.3.1234 |
| commission_from | Filter by any commission in the transaction | ex 1000 |
| commission_to | Filter by any commission in the transaction | ex 1000 |
| source | A valid lead source | ex propertyfinder |
| price_from | Filter by any negotiated price in the transaction | ex 1000 |
| price_from | Filter by any negotiated price in the transaction | ex 1000 |
| property_types | array of property type ids | ex 1 |
| property_category | Filter by property categeory | residential or commercial |
| commission_from | Filter by agent commission | Number format |
| commission_to | Filter by agent commission | Number format |
| lead | filter by lead | ex: '1' |
| landlord | filter by landlord | ex: '1' |
| reason | filter by reason | ex: 'test' |
| transaction_fields | filter on custom fields added in property | ex: transaction_fields => ['1' =>'shi'] |
| property_fields | filter on custom fields added in property | ex: property_fields => ['1' =>'shi'] |
| lead_fields | filter on custom fields added in lead | ex: lead_fields => ['1' =>'shi'] |
| landlord_fields | filter on custom fields added in landlord | ex: landlord_fields => ['1' =>'shi'] |
- Sorting :
| Name | Comment |
|---|---|
| reference | sorting by transaction reference |
| offering_type | sorting by transaction offering type (sale or rent) |
| price | sorting by transaction negotiated price |
| created | sorting by transaction creation date |
| updated | sorting by transaction last update date |
| lead | sorting by lead name |
| user | sorting by user name |
| status | sorting by status |
| gross_commission | sorting by grosse commission |
| total_commission | sorting by total commission (lead + owner) |
Create Transaction
- Endpoint:
POST /transactions
- Allowed for:
everyone can create a transaction
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| reference | string | yes | reference of transaction |
| type | string | yes | type of transaction (direct, indirect) |
| lead | integer | yes if direct |
The lead assigned to the transaction |
| landlord | integer | yes if direct |
The landlord assigned to the transaction |
| property or mls_property | integer | yes | Property or MLS property ID |
| negotiated_price | integer | yes if direct |
The price negotiated during the transaction |
| contract_signed_at | integer | yes if direct |
Date of the transaction |
| contract_signed_at | integer | yes if direct |
Date of the transaction |
| fields | array | optional | custom field list |
If the transaction is for a rent:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| contract_start_at | date | yes if direct |
Date when the contract starts |
| contract_end_at | date | yes if direct |
Date when the contract ends |
| deposit | array | no | A fix or percentage value |
| owner_commission | array | no | A fix or percentage value |
| tenant_commission | array | no | A fix or percentage value |
If the transaction is for a sale:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| date | date | yes if direct |
Date for the transfer to the property |
| down_payment | array | no | A fix or percentage value |
| buyer_commission | array | no | A fix or percentage value |
| seller_commission | array | no | A fix or percentage value |
When an array needs a fix or percentage value, one of these two following key will be required:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| value | integer | no | A fix value like 10000 |
| percentage | integer | no | A percentage from 0 to 100 |
For the contributors:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| tenant/owner | string | yes | string value |
| percentage | float | yes | Percentage |
| user | integer | yes | Id of user |
| linkedin_person | integer | yes | Id of contact |
| linkedin_company | integer | yes | Id of contact |
| client | null | yes | You don't need to specify a value for this contributor |
Only one key among client, user, linkedin_person and linkedin_company is required.
- JSON request example:
{
"transaction": {
"property" : 1,
"lead": 1,
"type": "direct",
"reference": "qwerty",
"negotiated_price": 1000,
"contract_signed_at": "2017-01-01",
"contract_start_at": "2017-01-01",
"contract_end_at": "2017-01-01",
"deposit": {
"value": 10000,
},
"owner_commission": {
"percentage": 2.5,
},
"tenant_commission": {
"percentage": 5,
},
"contributors": [
"tenant": [
{
"percentage": 12,
"user": 1
},
{
"percentage": 30,
"client": null
},
....
],
"owner": [
{
"percentage": 12,
"user": 1
},
{
"percentage": 30,
"client": null
},
....
]
],
"fields": {
"1": "2 pets", // id of the field => value of the field
"3": true
}
}
}
- JSON response:
This endpoint will return a Transaction.
Full update Transaction
- Endpoint:
PUT /transactions/{id}
- Allowed for:
users that has right property.update
- JSON request
The mandatory fields are similar than transaction creation, and also:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| status_reason | string | no | a comment when the transaction is set to lost |
| status_note | string | no | a note for the transaction |
| status_workflow | array | yes | mandatory when status_reason is set to Lost to competition |
The stucture of status_workflow:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| property_status | string | yes | new property status |
| lead_status | string | yes | new lead status |
- JSON response:
This endpoint will return a Transaction.
** Contributors will be returned if the request is marked as expanded **
- JSON response example:
{
"transaction": {
"property" : 1,
"lead": 1,
"type": "direct",
"reference": "qwerty",
"negotiated_price": 1000,
"contract_signed_at": "2017-01-01",
"contract_start_at": "2017-01-01",
"contract_end_at": "2017-01-01",
"deposit": {
"value": 10000,
},
"owner_commission": {
"percentage": 2.5,
},
"tenant_commission": {
"percentage": 5,
}
"contributors": {
"tenant": [
{
"id": 1,
"percentage": 5,
"user": {
"id": 1,
"public": {
"first_name": "Jon",
"last_name": "D",
"email": "admin@admin.com",
"licence": "XDXDSEF4",
"phone": "040404044",
"photo": {
"id": 11,
"thumb": {
"link": "https:\/\/s3-ap-southeast-1.amazonaws.com\/mycrm-internal-tests\/user\/thumb\/1\/foo.jpg",
"width": 200,
"height": 200
},
"full": {
"link": "https:\/\/s3-ap-southeast-1.amazonaws.com\/mycrm-internal-tests\/user\/full\/1\/foo.jpg",
"width": 540,
"height": 360
}
},
"descriptions": [
{
"lang": "en",
"content": "This is a description en"
},
{
"lang": "ar",
"content": "This is a description ar "
}
],
"position": null,
"linked_in": null,
"nationalities": null,
"languages": null
},
"private": {
"first_name": "Jon",
"last_name": "D",
"email": "admin@admin.com",
"mobile": "040404044",
"landline": null,
"landline_extension": null,
"lang": null,
"photo": {
"id": 11,
"thumb": {
"link": "https:\/\/s3-ap-southeast-1.amazonaws.com\/mycrm-internal-tests\/user\/thumb\/1\/foo.jpg",
"width": 200,
"height": 200
},
"full": {
"link": "https:\/\/s3-ap-southeast-1.amazonaws.com\/mycrm-internal-tests\/user\/full\/1\/foo.jpg",
"width": 540,
"height": 360
}
},
"use_email_signature": true,
"licence": "XD789GHT",
"email_signature": "My signature"
},
"role": "admin",
"created_at": "$userCreatedAt",
"updated_at": "$userUpdatedAt"
}
}
],
"owner": [
{
"id": 3,
"percentage": 25,
"user": {
"id": 3,
"public": {
"first_name": "Bob",
"last_name": "O",
"email": "bob.o@test.com",
"licence": "XDXDSEF5",
"phone": "040404044",
"photo": null,
"descriptions": [],
"position": null,
"linked_in": null,
"nationalities": null,
"languages": null
},
"private": {
"first_name": "Bob",
"last_name": "O",
"email": "bob.o@test.com",
"mobile": "040404044",
"landline": "040404044",
"landline_extension": "32",
"lang": null,
"photo": null,
"use_email_signature": null,
"licence": null
},
"role": "agent",
"created_at": "$userCreatedAt2",
"updated_at": "$userUpdatedAt2"
}
}
]
},
}
}
}
Patch update
PATCH /transactions/{id}
- JSON request
Change the status of the transaction:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| op | string | yes | Operation to execute (replace) |
| path | string | yes | Path "/status" to update the status. |
| value | object | yes | Details about the action |
Here the description of value object:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| status | string | yes | Can be "open", "won", "lost" |
| reason | string | yes | Reason for lost status |
| note | string | yes | Comment for the transaction |
| workflow | object | yes | Available if reason is set to Lost to competition |
The stucture of workflow:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| property_status | string | yes | new property status |
| lead_status | string | yes | new lead status |
- JSON request example:
{
"operations": [
{ "op": "replace", "path": "/status", "value": {"status": "lost", "reason": "good reason"} }
]
}
Change the assigned user:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| op | string | yes | Operation to execute (replace) |
| path | string | yes | Path "/assignment/user". |
| value | integer | yes | id of the user |
- JSON request example:
{
"operations": [
{ "op": "replace", "path": "/assignment/user", "value": 123 }
]
}
- JSON response:
Will return a 204 http code.
Bulk update Transaction
PATCH /transactions
- JSON request
Change the status of the transaction:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| op | string | yes | Operation to execute (replace) |
| path | string | yes | Path "/id/status" to update the status. |
| value | object | yes | status: value data (Can be "open", "won", "lost"). reason: string. The reason of the new status |
Change the assigned user:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| op | string | yes | Operation to execute (replace) |
| path | string | yes | Path "/id/assignment/user". |
| value | integer | yes | id of the user |
- JSON request example:
{
"operations": [
{ "op": "replace", "path": "/1/status", "value": {"status": "lost", "reason": "good reason"} },
{ "op": "replace", "path": "/1/assignment/user", "value": 123 }
]
}
- JSON response:
Will return a 204 http code.
Delete Transaction
- Endpoint:
DELETE /transactions/{id}
- Allowed for:
Admins only.
Curl example :
$ curl -X DELETE 'http://api-v2.mycrm.com/transactions/1'
Delete Transactions
- Endpoint:
DELETE /transactions
- Allowed for:
Admins only.
- JSON request:
An array of transaction ID.
- JSON request example:
{
"transactions": [
1, 2, 3
]
}
- JSON response:
Will return a 204 http code.