Introduction

Security and Authentication

15.01.2024 - Please contact our customer experience team to obtain the new integration credentials.

You must make sure that you have following 2 important information in order to proceed with integration.

API Key : Clients unique identifier on PF Expert
API Secret : Clients secret to authenticate before issuing access token

In Basic HTTP authentication, a request contains a header field in the form of Authorization: Basic {credentials} , where credentials is the Base64 encoding of API key and API secret joined by a single colon :

Once you have the required API credentials, you need to request for an access token using the integration credentials.

Token Endpoint :

POST https://auth.propertyfinder.com/auth/oauth/v1/token
Authorization: Basic {BASE64_VALUE}
{
    "scope": "openid",
    "grant_type": "client_credentials"
}

An access token will be issued which will expire in 30 minutes. Once token is expired, a fresh token must be requested. No refresh token flow is supported in this integration.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cC....rvfrLQrc5rgH30SoJQee1LBHXk9UmwnrUzm64M91w",
  "token_type": "Bearer",
  "expires_in": 1800
}

Once token is issued, it must be sent as a Bearer i.e. Authorization Bearer {access_token}.

curl -H "Authorization: Bearer {access_token}" https://api-v2.mycrm.com/{api_endpoint}

Some custom headers will provide some extra information :

X-MyCRM-API-Warning will give you some warning about the related request
X-MyCRM-Expand-Data will provide more information about the related request (not available on all request)

The expanded data refers only related object to the requested resource (example : agent related to the property, landlord related to the property, etc.). By default, any related object is not expanded and only the id is returned. The header will allow you to return the full object instead of the object id. About related objects list, they won't be returned by default. Only the header will allow you to retrieve collection related to the current object.

Http code

MyCRM responds to successful requests with HTTP status codes in the 200 or 300 range. When you create or update a resource, MyCRM renders the resulting JSON representation in the response body and set a Location header pointing to the resource. Example:

Status: 201 Created
Location: https://api-v2.mycrm.com/users/123

{
  "user": {
    "id": 123,
    "first_name": "James",
    ...
    "created_at": "2012-04-04T09:14:57Z"
  }
}

MyCRM responds to unsuccessful requests with HTTP status codes in the 400 range.

According to the W3C, here the list of the http code we will use :

Http code	Comment
200	The request has succeeded
201	The request has been fulfilled and resulted in a new resource being created
204	The server has fulfilled the request but does not need to return an entity-body
400	The request has failed
401	The token is missing or incorrect
403	The resource need more authorizations
404	The requested resource or the requested route does not exist
500	An internal error has occurred

Response error

An error will provide an 400 range http code. The error code provided will me among the following list: * ResourceNotFound : Missing resource (e.g a non existing user, non existing route etc.) * InvalidRequest : POST, PUT or PATCH method that is malformed (e.g missing fields, bad format fields, etc) * MethodNotAllowed : Bad HTTP method * InternalError : API is not able to describe the current error * AuthenticationError : Authentication is required, either it's missing or invalid * AccessDenied : Not enough permission * InvalidAction : The request contains invalid action

Response that contains an error will have the following format:

{
  "user": "ResourceNotFound",
  "messages" : [
    "No route found for \"GET \/users\/foo\/bar\""
  ]
}

Response fields

By default, all described fields in the endpoint will be returned. You can defined a list of fields that only should be returned. You can define these filters with the "field" parameter :

curl -H "Token: {token}" https://api-v2.mycrm.com/users/1?fields=id,first_name

{
  "user": {
    "id": 123,
    "first_name": "James",
  }
}

Pagination

By default, most list endpoints return a maximum of 100 records per page. You can change the number of records on a per-request basis by passing a per_page parameter in the request URL parameters. Example: per_page=50. However, you can't exceed 100 records per page on most endpoints.

When the response exceeds the per-page maximum, you can paginate through the records by incrementing the page parameter. Example: page=3.

List also include the total count of the available items:

{
  "count": 1234,
  "page": 1,
  "per_page": 100,
  "users": [ ... ],
}

The sorting will use sort and sort_order parameters.