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.