Getting Started
Welcome to the Perch API, a specialized interfacing platform created to expand the possibilities with which Perch partners interact with our digital mortgage brokering ecosystem.
The Perch API is not your typical public-facing interface; it's a bespoke solution that has been intricately designed to meet the unique requirements of our internal operations and, now by extension, the needs, hopes and dreams of our valued partners like you!
The primary goal in exposing a public API is to enable Perch partners to seamlessly expand their business operations and offerings with the support of our digital mortgage brokering solutions and in turn add new value to their existing clients.
Introduction
The Perch API is organized around both restful and workflow type endpoints. You can expect predictable endpoint URLs for both the restful (/parentResources/:id/childResource) and workflow (/workflows/:workflow-id) endpoints. All of our endpoints accept and respond with JSON, using standard HTTP status codes for responses.
You will be able to use our API in both a sandbox environment as well as the live environment. Of course, use of the sandbox environment is highly encouraged while testing your integration as data submitted through the live environment will be treated as such and in many cases trigger automated workflows and/or customer service representative intervention.
Your domain and API key will dictate which environment is in use.
Terms of Use
By accessing or using the Perch API (the "API"), you (the "Client") agree to be bound by the following Terms of Service ("TOS"). These terms govern your use of the API, which is provided by Perch (the "Service Provider"). If you do not agree to these terms, you must not use the API.
The Perch API enables integration with Perch’s platform, providing secure access to its data and services. These TOS are designed to ensure proper use of the API, maintain its security, and protect the interests of both parties.
The Service Provider reserves the right to update or modify these TOS at any time. Significant changes will be communicated, and continued use of the API after such changes constitutes your acceptance of the updated terms.
Please review the terms carefully, as violations may result in suspension or termination of your API access.
API Key Security and Access
- The API key provided by the Service Provider is confidential and must be stored securely by the Client.
- API keys shall not be exposed in front-end applications, shared publicly, or embedded in publicly accessible repositories or code.
- The Client is responsible for maintaining the confidentiality of their API keys and any activities that occur under their account.
- The Client must notify the Service Provider immediately of any unauthorized use, security breach, or compromise of their API key.
- The Service Provider will treat the Client's API keys as confidential and will not disclose them to third parties.
Rate Limits and Usage
- The Client agrees to adhere to the API rate limits as outlined in the Service Provider’s documentation. Excessive requests may result in throttling, suspension, or termination of access.
- The Client shall only use the API for purposes specified during onboarding or as agreed in writing with the Service Provider. Unauthorized, malicious, or exploitative use of the API is prohibited.
Data Privacy and Security
- The Client agrees to handle all data obtained via the API in compliance with applicable data protection laws. Sensitive user data shall not be stored unless explicitly permitted by the Service Provider.
- The Service Provider will maintain commercially reasonable security precautions to prevent unauthorized access to the API and Client data.
- The Client acknowledges that using the API and connecting to the internet presents risks, including unauthorized third-party access, and agrees to take appropriate measures to secure their systems.
Modifications to the API
- The Service Provider may modify the API, including rate limits, endpoints, or features, and will provide prior notice where feasible.
- The Client agrees to update their integration to remain compatible with any modifications to the API.
Liability
- The Service Provider is not liable for any direct or indirect damages resulting from the use or inability to use the API, including but not limited to service interruptions or data loss.
Termination
- The Service Provider reserves the right to terminate access to the API if the Client breaches any term of this Agreement or engages in misuse of the API.
- Termination for cause does not preclude additional remedies available under the law.
Overview
To make use of the Perch API you will need both your API key and the Open API Specification document (OAS 3.x) for the Perch API.
From this point on, we will assume that you have imported the OAS document into Postman. You can follow our Postman Setup guide to get started with that.
Authentication
The Perch API uses API keys for authentication.
Each API key belongs to a specific Firm and role type within our system. The key will be granted permissions based on the particular API functions your specific implementation requires.
The API key must be sent to the Perch API using the X-API-Key (case-insensitive) HTTP header.
As is the case with any API key, you should ensure that all connections to our API are encrypted and made from a backend system, rather than client side (e.g., from a client facing web browser) where a key can be accessed by a 3rd party.
Perch is not responsible for the breach or loss of your data due to exposure of your API key to 3rd parties.
Domains
The Perch API provides separate domains for our different API user roles and use cases. For external use, that is currently limited to our Realtor and Partner APIs. In order to use the correct API, you will only need to select the correct domain:
Errors
Perch uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Perch's servers (these are rare, but they can happen).
The error will contain a helpful message and, in some cases (409 and 422), a fields object. The fields object will contain fields that failed some validation and an array of validation errors.
// 409 - Conflict
// This error indicates that a duplicate record exists for the parent (resourceId and resourceType polymorphic association) and the supplied email address.
{
"message": "Failed to create the Lead",
"fields": {
"resourceId": [{
"code": "NOT_UNIQUE",
"message": "Failed to pass unique index constraint",
}],
"resourceType": [{
"code": "NOT_UNIQUE",
"message": "Failed to pass unique index constraint",
}],
"email": [{
"code": "NOT_UNIQUE",
"message": "Failed to pass unique index constraint",
}]
}
}Soft Deletion
Many of the resources in our system support soft-deletion, which we call "paranoid" resources. This means that records will not be removed from the database, but instead get a timestamp value set to the record's deletedAt column. Deleted records will not be returned or accessible by default via our endpoints.
However, we do still offer a way to view these deleted records, using the scopes query option on our GET endpoints. You can read more about this in our query parameters documentation.
Rate Limiting
Please take note that requests will be rate limited based on an hourly quota. The quota will allow for burst requests of up to 6x the hourly average quota.
For example, if your quota is 500 requests / hour, then you cannot exceed 50 requests / minute. The hourly quota is rolling, so if you made 500 requests between 07:30 and 07:45, then you must wait until 08:30 before you can continue to use the API.
Restful Resources
Workflows
Advanced Topics
Restful Query Parameters
Pagination
By default, all index (i.e., GET /resources) calls to our API will be paginated. To paginate the API, you can use the limit and offset query parameters (e.g., GET /resources?limit=20&offset=40; page 3 with 20 records per page).
Order
Similar to pagination, index calls will be sorted by ['createdAt', 'DESC']. You can override this by passing a new field and sort direction (i.e., 'ASC' or 'DESC'). For example, GET /resources?order=[['email', 'ASC']].
Filters
When calling a restful GET endpoint, we support passing along filters to restrict the data that is passed back. These filters are a JSON object of fields as keys and exact values. For example, GET /resources?filter={"email": "john.doe@example.com"}. Depending on the tool you are using, you may need to URL encode the JSON before sending the request.
Scopes
The Perch API uses scopes to simplify common or complicated queries, or to perform requests that fall outside of the restful capabilities. For example, in order to fetch deleted resources, you would pass the withDeleted scope in your request (e.g., GET /resources?scope=withDeleted). Not all scopes are available for each resource, so keep an eye out on each resource to understand which scopes are supported.