​
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. Before using the Perch API, please review our Terms of Use which outline important legal requirements, security obligations, and usage policies.

​
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:
API TypeDIT DOMAINPRODUCTION DOMAIN
Realtorapi.realtor.dit.myperch.ioapi.realtor.myperch.io
Partnerapi.partner.dit.myperch.ioapi.partner.myperch.io
Always start with the DIT (development/sandbox) domain for testing your integration before switching to production.

​
Restful Resources

The majority of uses of the Perch ecosystem can be managed via Perch’s Restful API. Our RESTful endpoints follow predictable patterns:
  • GET /resources - List resources (with pagination)
  • GET /resources/:id - Get a specific resource
  • POST /resources - Create a new resource
  • PATCH /resources/:id - Update an existing resource
  • DELETE /resources/:id - Delete a resource (soft delete)
For detailed information about each resource and its schema, see the Partner API Reference.

​
Workflows

Workflows allow for non-restful interactions with the Perch system. This may be a multi-step action that impacts multiple resources, an action that has a more nuanced access control, or an action that requires non-restful parameters. To ensure all API actions conform to ACID principles, we provide simplified interfaces for these complex actions in the form of workflows. Workflow endpoints follow the pattern: /workflows/:workflow-id

​
Getting Your API Credentials

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. To get started:
  1. Contact partnersupport@myperch.io to request API access
  2. You’ll receive your API key and access to the appropriate API specification
  3. Follow our Postman Setup guide to import the API specification
  4. Review our Authentication guide for implementation details

​
Next Steps