DEVELOPER HUB
Embeddable Tools
Missing documents? 
Make sure you sign in to your account.

Submitting & Tracking Leads

Perch created it's public API to provide our partners with an easy to use, mortgage as a service (MaaS) offering. Using the Perch API partners can programmatically drive mortgage seekers towards securing mortgage products through Perch's online ecosystem (purchase, renewal, refinance, etc.).

This guide provides detailed steps and examples on how your company can integrate our Leads submission and monitoring functionality into your internal systems.

To use this guide you will need the following pieces of data (all of which are provided to you by Perch).
  1. x-api-key: A UUID V4 which grants you access the Perch API.
  2. Firm.id: The unique identifier of your firm.
  3. ReferralCode.id: The unique identifier of your firm's referral code.

1. Creating a Lead

Leads is a group of highly flexible endpoints which enable the submission of customer data to Perch (refer to the Leads API Spec).

Using the Perch API partners can:

  1. Remove much of the overhead in the client's application process by proactively populating a client profile prior to that client's registration with Perch.
  2. Track the status of the submitted Lead (i.e. have they completed registration with Perch).
To implement such functionality, you may consider creating a lead submission form within the client profile page of your CRM. Your account managers can use this form to create a Lead in Perch after identifying the client is a good fit for Perch's product offering. You could design the form to accept custom parameters like notes and the deal purpose to better define the engagement opportunity for Perch's Customer Success Team.

The more detail provided when creating a Lead, the simpler the application process for the client as they will not need to re-enter these details when they enter the Perch ecosystem. Instead, when a client completes account registration, all data submitted as part of their associated Lead will automatically be populated on their Client's profile.

Rest assured, Perch has prioritized the security of your data. Perch employs robust encryption measures to safeguard all Lead data, both at rest and in transit, ensuring your clients' sensitive information remains protected.

Upon submitting a Lead to Perch you can expect:

  • The Lead will be populated in Perch's database and made accessible via GET and update it via PATCH.
  • Perch will immediately send a personalized welcome message to the email address provided in the Lead request. The email will provide a brief overview of Perch and invite the user to sign up. Please note that this email can be disabled if you wish to send your own automated communication.
  • Perch's customer experience team will automatically be deployed to help assist in onboarding the Lead.
  • When the client signs up for Perch their lead data will be converted into a client profile (we call this "conversion"). The lead object will be updated with a convertedAt date, a deletedAt date (the lead is automatically archived upon conversion) and if Plan data was included in the lead 's clientData object then the plan(s) will be created and the lead will be updated with the related plan_id so that you can look the plan(s) up directly.

‍Important: to automatically populate the client's profile with the submitted Lead data, the client must sign up using the same email address that was used to create the Lead.

To create a Lead, make a POST request to the endpoint /firms/{firm_id}/leads. Upon successful creation of a Lead we recommend storing the Lead.id primary key so that you can periodically check for updates on the Lead's conversion (i.e. did they actually sign up).

EXAMPLE REQUEST
curl -X POST 'https://api.partner.myperch.io/v1/firms/{firm_id}/leads' \
-H 'x-api-key: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
    "email": "elliot91@yahoo.com",
    "firstName": "Elliot",
    "lastName": "Lynch",
    "phone": {
      "number": "0788243632",
      "extension": "402"
    },
    "clientData": {
      "prefix": "Ms.",
      "citizenship": "Permanent Legal Resident (PR)",
      "dateOfBirth": "1968-09-25",
      "maritalStatus": "Single",
      "isFirstTimeHomeBuyer": false,
      "notes": "Lorem ipsum..."
    }
}'
Example Response
{
  "data": {
    "id": "cXzT1EtA",
    "createdAt": "2023-12-12T00:31:42.155Z",
    "updatedAt": "2023-12-12T00:31:42.155Z",
    "email": "elliot91@yahoo.com",
    "firstName": "Elliot",
    "lastName": "Lynch",
    "phone": {
      "number": "0788243632",
      "extension": "402"
    },
    "clientData": {
      "prefix": "Ms.",
      "citizenship": "Permanent Legal Resident (PR)",
      "dateOfBirth": "1968-09-25",
      "maritalStatus": "Single",
      "isFirstTimeHomeBuyer": false,
      "notes": "Lorem ipsum..."
    },
    "resourceType": "Firm",
    "resourceId": "mctTVsRB",
    "deletedAt": null,
    "convertedAt": null
  }
}
This request will create a new Lead associated with your firm, with details like email, name, and client data. Firms is the resource used to denote partner organizations. In this case the :id will be your firm's unique Firm.id value which will be provided by your Perch account representative.

2. Monitoring the conversion status of a Lead

You can monitor the status of a Lead by making a GET request to /leads/{lead_id}. The convertedAt parameter in the response indicates if/when the lead was converted for a ClientProfile.

Please make sure you use ?scope=withDeleted to ensure that the endpoint returns even deleted Leads.
Example REQUEST
curl -X GET 'https://api.partner.myperch.io/v1/leads/{lead_id}?scope=withDeleted' \
-H 'x-api-key: your_api_key'
Example Response
{
  "data": {
    "id": "cXzT1EtA",
    "createdAt": "2023-12-12T00:31:42.155Z",
    "updatedAt": "2023-12-12T00:31:42.155Z",
    "email": "elliot91@yahoo.com",
    "firstName": "Elliot",
    "lastName": "Lynch",
    "phone": {
      "number": "0788243632",
      "extension": "402"
    },
    "clientData": {
      "prefix": "Ms.",
      "citizenship": "Permanent Legal Resident (PR)",
      "dateOfBirth": "1968-09-25T10:36:49.352Z",
      "maritalStatus": "Single",
      "isFirstTimeHomeBuyer": false
    },
    "resourceType": "Firm",
    "resourceId": "mctTVsRB",
    "deletedAt": "2023-12-12T00:31:42.370Z",
    "convertedAt": "2023-12-12T00:31:42.350Z"
  }
}
The convertedAt datetime value denotes the time at which the Lead was promoted from a Lead to a ClientProfile. In most cases, this is when the client completes the Perch registration process.
The deletedAt datetime value is set at the same time as convertedAt to automatically archive the lead record by setting the deletedAt value. If a Perch Representative archives a Lead the deletedAt value will be populated, but the convertedAt value will not.

When a lead converts, you can expect the following:

  • The Lead record will receive a one time update in which the convertedAt and deletedAt value will be set.
  • All Firm Member owners associated with the Firm, who have an active Perch Notification subscription will receive an email alert letting them know the lead has converted.
  • If Plans were was included in the ClientData of the Lead, a planId will also be set in the Plan object response. You can use this plan_id to access the Plan details. You can learn more about including Plan data in your Lead in section 4 below.

3. Retrieve all Leads for a Given Firm

In the event that you would like to see all the leads you've created for your firm you can use the GET firms/:id/leads endpoint.
Example REquest
curl -X GET 'https://api.partner.myperch.io/v1/firms/{firm_id}/leads' \
-H 'x-api-key: your_api_key'
The response returned will contain an array of Leads created by the provided Firm. The default list limit is 50 and offset is 0. Please refer to our detailed API documentation to learn about the use of params like limit and offset to page through results.

4. Creating a Lead with Plan data (i.e. defining the deal purpose)

In the Perch ecosystem, a Plan is simply the name we've given to the resource which contains details related to one or more mortgage applications (e.g. home buying plan, refinancing plan, etc.). Since it is possible for a client to have simultaneous mortgage applications (e.g 1st & 2nd position mortgage / 1st position mortgage + HELOC), we created the Plans resource to allow for the bucketing of the related applications. You can assume that 90% of the time a Plan has only one mortgage application.

It is important to note, that your API access to Plans is granted either through the Plan.referralCodeId or the Plan.partnerFirmId values that can be set on any given plan. When you provide Plan data as part of your Lead submission, we will automatically add your referralCode to the Plan(s) created on conversion. In turn, you will be granted limited access to these Plans where you are marked as referral source, for plan completion tracking purposes (More: Retrieving All Plans for a given ReferralCode ). On the other hand, you MUST manually add the ParterFirmId value in your request if you want to be set as the partner firm on the plan. Being set as the partner firm give you additional access to the plan and the client will be made aware of this data sharing as part of their experience within our portals.

To protect Client privacy, Plans created by a client after registration will not automatically be accessible by the Lead owner. Only plans where you have been set as the referral source can be accessed.

It is possible to provide you with access to a plan retroactively, but requires manual intervention by Perch's Customer Experience team.

Including Plan data when creating a lead is simple as seen in the example below. Notice the inclusion of Plans array in the request body. In this case we are including one plan with the deal purpose of Buying (Please see planTypes in our full API documentation). Plans is an array and accepts one or more values.

Example REquest
curl -X POST 'https://api.partner.myperch.io/v1/firms/{firm_id}/leads' \
-H 'x-api-key: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
    "email": "elliot91@yahoo.com",
    "firstName": "Elliot",
    "lastName": "Lynch",
    "phone": {
      "number": "0788243632",
      "extension": "402"
    },
    "clientData": {
      "prefix": "Ms.",
      "citizenship": "Permanent Legal Resident (PR)",
      "dateOfBirth": "1968-09-25T10:36:49.352Z",
      "maritalStatus": "Single",
      "isFirstTimeHomeBuyer": false,
      "notes": "Lorem ipsum",
      "Plans": [
        {
          "type": "Buying",
          "partnerFirmId": your_firm_id,
        }
      ]
    }
}'
Example RESPONSE
{
  "data": {
    "id": "cXzT1EtA",
    "createdAt": "2023-12-12T00:31:42.155Z",
    "updatedAt": "2023-12-12T00:31:42.155Z",
    "email": "elliot91@yahoo.com",
    "firstName": "Elliot",
    "lastName": "Lynch",
    "phone": {
      "number": "0788243632",
      "extension": "402"
    },
    "clientData": {
      "Plans": [
        {
          "type": "Buying",
          "partnerFirmId": your_firm_id,
        }
      ]
    },
    "resourceType": "Firm",
    "resourceId": "mctTVsRB",
    "deletedAt": null,
    "convertedAt": null
  }
}

In the event where the lead has converted, you can expect the Plan object to contain an plan.id value which you can use to retrieve that plan's details. The plan is automatically created during the lead conversion workflow (i.e. when the lead accepts the invitation and signs up for Perch).

5. Retrieving Plans to which you have ownership access

5.1 Get Plans where you are the Partner Firm

When you create a Lead with one or more Plans, and need access to the plan details after creation ( e.g. detailed plan data, pre-approval information, etc.), be sure to set your firmId as the partnerFirmId value (see #4 above for more information) in the plan object to your  firmId. This ensures your firm will automatically be set as the partner firm (i.e. via Plan.partnerFirmId) on the Plan during the conversion process. To view a list of all Plans where you are the partner firm, you can use the GET firms/{firm_id}/plans endpoint. You can also access an individual plan where you are the partner firm using the /plans/{plan_id} endpoint. In the event where you are unable to access a plan to which you believe you should have access, it is possible you were removed as the partner firm. In this case please reach out to our customer support team to investigate the issue.

Example REquest
curl -X GET 'https://api.partner.myperch.io/v1/firms/{firm_id}/plans' \
-H 'x-api-key: your_api_key'

This request fetches all plans linked to the provided firmId value, providing a snapshot of the current mortgage applications that you are able to access. Please note, you may have access to Plans you did not create through Leads if you have been set as the partner firm on other Plans. This means you can check the Plan.status and other details of these plans as well.

The response returned will contain an array of Plans owned by the provided firmId. The default list limit is 50 and offset is 0. Please refer to our detailed API documentation to learn about the use of params like limit and offset to page through results.

5.2 Get Plans where you are the Referrer

To view a list of all Plans that where you have been deemed as the referrer and where you may be granted referral commission, you can use the GET referralCodes/{referral_code_id}/plans endpoint. When you create a Lead with one or more Plans, your firm is automatically set as the referral source (i.e. via Plan.referralCodeId) on the Plan during the conversion process. You may wish to

Example REquest
curl -X GET 'https://api.partner.myperch.io/v1/referralCodes/{referral_code_id}/plans' \
-H 'x-api-key: your_api_key'

This request fetches all plans linked to the provided referralCodeId value, providing a snapshot of the current mortgage application that you are able to access. Please note, you may have access to Plans you did not create through Leads if you have been set as the referral source on other Plans. This means you can check the Plan.status of these plans as well to determine the status of your commission payment. Referral comissions are paid only on completed plans.

The response returned will contain an array of Plans owned by the provided referralCodeId. The default list limit is 50 and offset is 0. Please refer to our detailed API documentation to learn about the use of params like limit and offset to page through results.

Important: Your Firm's  firmId and referralCodeId are not the same value. Your Perch account representative will provide you with both of these values.

6. Updating a Lead

You can continue to update a Lead with additional details up until the point where the lead has converted (as denoted by the convertedAt and deletedAt datetime value being set). Updating a Lead after conversion is not advantageous as the conversion process whereby lead data populates the client's profile will have already taken place.

You can update a lead though the PATCH /leads/{lead_id}.

Example REquest
curl -X PATCH 'https://api.partner.myperch.io/v1/leads/{lead_id}' \
-H 'x-api-key: your_api_key'

7. Disabling Perch's default outreach automation when creating a Lead

As discussed above, when a Lead is created to Perch, we automatically send a welcome message to the the email address in the submitted Lead. To disable this default messaging when creating a Lead, you can use the disableClientOutreach parameter in your POST /firms/{firm_id}/leads/.

You may wish to apply this flag, if you want to manage your own automated lead outreach messaging strategy.

Example REquest
curl -X POST 'https://api.partner.myperch.io/v1/firms/{firm_id}/leads?disableClientOutreach=true' \
-H 'x-api-key: your_api_key' \
-H 'Content-Type: application/json' \
-d '{
    "email": "client1@yahoo.com",
    "firstName": "Billy",
    "lastName": "Bob",
    "phone": {
      "number": "2223334444"
    },
}'

8. Retrieving all Leads for your Firm (Including Deleted Leads)

To get all leads for your firm, including those that have been deleted, use the withDeleted scope in your GET /firms/{firm_id}/leads:

Example REquest
curl -X GET 'https://api.partner.myperch.io/v1/firms/{firm_id}/leads?scope=withDeleted' \
-H 'x-api-key: your_api_key'

This request will return both active and deleted lead records, providing a comprehensive view of all leads associated with your firm.