Introduction
The Payroll API is a REST API allowing authorized clients to consume data that includes broker, lender, and deal information. Follow the application to completion by watching deal and compliance status updates.
Our project team will gladly work through a plan to get you connected to our Payroll API by setting up a development sandbox with access application data so that you can work independently on your solution. We will share our experiences and best practices to make this process as smooth as possible.
Authentication
POST https://api-link.newton.ca/payroll/token HTTP/1.1
Content-Type: application/json
Request
{
"username" : "<username>",
"password" : "<password>"
}
Response
{
"token": "ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...",
"message": "Success"
}
Payroll API consumers must be authenticated and authorized to make API calls.
Payroll API uses JSON Web Tokens (JWTs) to authenticate requests. Successful authentication request will return an access token that is valid for 1 hour. All API calls must include an access token (bearer) in the Authorization header.
Consumers are encouraged to cache and reuse access tokens and only issue an authentication request before an API call if the token had expired or is about to expire.
Authorization
Payroll API access token's claims indicates which request methods can be performed and what data will be returned by the API.
An access token will contain one of the following claims:
https://claim.newton.ca/tenant - grants access to broker and deal data from specific tenantshttps://claim.newton.ca/firm - grants access to broker and deal data from specific firmshttps://claim.newton.ca/network - grants access to broker and deal data from specific networks
If
If
Definitions
GET https://api-link.newton.ca/payroll/v2/definitions
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...
Retrieves a list of enumerator definitions that are used in deal details. Some of these enumerators can also be used for filtering deals returned in Deals operation.
LenderID property returned by the Definitions operations is marked
Responses
Sample Response
200 Response
{
"dealStatusID": {
"1": "New",
"2": "Submitted",
"3": "Approved"
},
"mortgagePositionID": {
"1": "First",
"2": "Second",
"3": "Third"
},
"purposeID": {
"0": "Purchase",
"2": "Refinance",
"3": "ETO"
}
}
Status | Schema |
---|---|
200 OK | Definitions |
Definitions
Name | Type | Description |
---|---|---|
lenderID |
object nullable | List of lenders (key-value pairs) |
dealStatusID | object nullable | List of deal statuses (key-value pairs) |
mortgagePositionID | object nullable | List of mortgage positions (key-value pairs) |
purposeID | object nullable | List of mortgage purposes (key-value pairs) |
paymentFrequencyID | object nullable | List of payment frequencies (key-value pairs) |
rateTypeID | object nullable | List of rate types (key-value pairs) |
mortgageTypeID | object nullable | List of mortgage types (key-value pairs) |
streetTypeID | object nullable | List of street types (key-value pairs) |
importStatusID | object nullable | List of import statuses (key-value pairs) |
filterModeID | object nullable | List of filter modes (key-value pairs) |
complianceStatusID | object nullable | List of compliance statuses (key-value pairs) |
posSystemID | object nullable | List of PoS systems (key-value pairs) |
Lender
GET https://api-link.newton.ca/payroll/v2/lenders
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...
Get a list of lenders, their codes and names. This list changes often and should be consumed for updates on a regular basis.
Responses
Sample Response
200 Response
[
{
"code": 1654,
"name": "Canadian Mortgages Inc"
},
{
"code": 1972,
"name": "Equitable Bank"
},
{
"code": 1269,
"name": "First National Financial"
},
{
"code": 1054,
"name": "Fisgard Asset Management"
},
{
"code": 1479,
"name": "Haventree Bank"
},
{
"code": 1279,
"name": "Home Trust"
},
{
"code": 1387,
"name": "Manulife Bank"
},
{
"code": 1978,
"name": "MCAP Mortgage Corporation"
},
{
"code": 1499,
"name": "Scotiabank / Banque Scotia"
},
{
"code": 1237,
"name": "TD Mortgage Services"
}
]
Status | Schema |
---|---|
200 OK | array(Lender) |
Lender
Name | Type | Description |
---|---|---|
code | integer(int32) | Lender code |
name | string nullable | Lender name |
Brokers
GET https://api-link.newton.ca/payroll/v2/brokers
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...
GET https://api-link.newton.ca/payroll/v2/{networkcode}/brokers
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...
Retrieve a list of the brokers/agents and their details. This list changes often and should be consumed for updates on a regular basis.
Parameters
Name | In | Type | Description |
---|---|---|---|
networkCode | path | string | Brokerage network code |
Responses
Sample Response
200 Response
[
{
"agentID": "af269125-2abd-42b1-86b4-647130e6ac94",
"expertUsername": "JSMITH",
"expertProfileId": "36453",
"firmCode": "ABCD",
"name": "John Smith",
"username": "john.smith",
"linkId": "jsmith100",
"licenseeId": "ABCD0001",
"shortCode": "i2otUV45QTht",
"publicURL": "https://<client-journey-url>/sso/public.php?sc=i2otUV45QTht"
},
{
"agentID": "92200fa3-3f39-46a7-bdc4-b22490c34a78",
"expertUsername": "RBERRY",
"expertProfileId": "1673",
"firmCode": "ABCD",
"name": "Robert Berry",
"username": "robert.berry",
"linkId": "rberry100",
"licenseeId": "ABCD0001",
"shortCode": "o1Cr6OgJ9L1X",
"publicURL": "https://<client-journey-url>/sso/public.php?sc=o1Cr6OgJ9L1X"
},
{
"agentID": "cf609321-cf27-4233-80ea-33f31a97602b",
"expertUsername": "DBROWN",
"expertProfileId": "38363",
"firmCode": "ABCD",
"name": "David Brown",
"username": "david.brown",
"linkId": "dbrown100",
"licenseeId": "ABCD0001",
"shortCode": "Q5KleYLCm135",
"publicURL": "https://<client-journey-url>/sso/public.php?sc=Q5KleYLCm135"
}
]
Status | Schema |
---|---|
200 OK | array(Agent) |
Agent
Name | Type | Description |
---|---|---|
agentID | string(uuid) | Unique agent identifier |
expertUsername | string nullable | Agent's username as appears in Expert |
expertProfileId | string nullable | Agent's Expert profile Id |
firmCode | string nullable | Agent's firm code |
name | string nullable | Agent's full name |
username | string nullable | Agent's username |
linkId | string nullable | Agent's Link ID |
licenseeId | string nullable | Agent's tenant code (licenseeId) |
removedDateTimeUTC | string(date-time) nullable | Timestamp when agent was removed |
shortCode | string nullable | Agent's short code |
publicURL | string nullable | Client Journey URL |
Deal
GET https://api-link.newton.ca/payroll/v2/deals
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...
GET https://api-link.newton.ca/payroll/v2/{networkcode}/deals
Content-Type: application/json
Authorization: Bearer ie7JIONyQC8EdP4LCaJXn9HkkxnMt-VQ9D3a4SghfhCXITf_WoFop7tNnwu7-6SxViCQX...
Filter and retrieve deal information required for payroll processing that includes borrower, subject property, mortgage, lender and compliance statuses.
Parameters
Name | In | Type | Description |
---|---|---|---|
networkCode | path | string | Brokerage network code |
hoursBack | query | integer(int32) | Hours back |
loanCode | query | string | Loan code |
expertLoanCode | query | string | Expert loan code |
posSystemId | query | integer(int32) | PoS system |
firmCode | query | string | Firm code |
licenseeId | query | string | Tenant code |
officeName | query | string | Office name |
username | query | string | Username |
expertUsername | query | string | Expert username |
closingDateFrom | query | string(date-time) | Earliest closing date |
closingDateTo | query | string(date-time) | Latest closing date |
limitTotalResults | query | integer(int32) | Maximum number of results |
lenderId | query | integer(int32) | Lender code |
lenderName | query | string | Lender name |
clientFirstName | query | string | Applicant's first name |
clientLastName | query | string | Applicant's last name |
coClientFirstName | query | string | Co-applicant's first name |
coClientLastName | query | string | Co-applicant's last name |
hasCreditBureau | query | boolean | With credit bureau? |
cb |
query | boolean | With credit bureau? |
lenderReferenceNumber | query | string | Lender reference number (Application number) |
dealStatusID | query | integer(int32) | Status |
importStatusID | query | string | Import status |
filterMode | query | FilterMode | Filter mode |
Responses
Sample Response
200 Response
[
{
"posSystemId": 40,
"brokerNetwork": "DLC",
"firmCode": "ABCD",
"licenseeId": "ABCD0001",
"officeName": "Mortgage Financial Partners",
"organizationName": "Mortgage Financial Partners",
"expertProfileId": "36453",
"username": "john.smith",
"linkId": "jsmith100",
"agentName": "John Smith",
"agentID": "af269125-2abd-42b1-86b4-647130e6ac94",
"loanCode": "VDLC-41203",
"applicationDate": "2023-07-31T18:32:18",
"dateUpdated": "2023-07-31T11:43:35",
"dealStatusID": 1,
"clientFirstName": "Brooke",
"clientLastName": "Drummond",
"clientDOB": "1987-07-27",
"clientPhone": "6405559898",
"clientEmail": "brooke.drummond@example.com",
"streetNumber": "8899",
"streetName": "Birnam",
"streetType": "Drive",
"streetTypeID": 9,
"city": "Ilderton",
"province": "Ontario",
"postalCode": "N0K1B0",
"mortgagePositionID": 1,
"lenderID": "1499",
"lenderName": "Scotiabank / Banque Scotia",
"fundedAmount": 648000,
"mortgageRate": 0,
"mortgageAmortization": 25,
"closingDate": "2023-12-14",
"maturityDate": "2023-12-14",
"purposeID": 0,
"paymentFrequencyID": 3,
"private": false,
"fixed": false,
"isCommercialDeal": false,
"firstTimeBuyer": true,
"isConnectCompliance": true,
"readyForCompliance": false,
"complianceConfirmed": false,
"complianceStatusID": 0
},
{
"posSystemId": 40,
"brokerNetwork": "DLC",
"firmCode": "ABCD",
"licenseeId": "ABCD0001",
"officeName": "Mortgage Financial Partners",
"organizationName": "Mortgage Financial Partners",
"expertProfileId": "1673",
"username": "robert.berry",
"linkId": "rberry100",
"agentName": "Robert Berry",
"agentID": "92200fa3-3f39-46a7-bdc4-b22490c34a78",
"loanCode": "VOHFP-54623",
"submissionReferenceNumber": "M101319878",
"lenderReferenceNumber": "OHFP.0002619",
"applicationDate": "2022-02-09T17:39:55",
"dateUpdated": "2023-09-11T12:21:43",
"creditBureau": "TransUnion",
"dealStatusID": 2,
"clientFirstName": "Luis",
"clientLastName": "Diaz",
"clientDOB": "1982-02-02",
"clientPhone": "9556565655",
"clientEmail": "luis.diaz@example.com",
"streetNumber": "34",
"unitNumber": "23",
"streetName": "Hollywood",
"streetType": "Carrefour",
"streetDirection": "S",
"city": "Toronto",
"province": "Ontario",
"postalCode": "M2N0A9",
"mortgagePositionID": 1,
"lenderID": "1499",
"lenderName": "Scotiabank / Banque Scotia",
"fundedAmount": 640000,
"mortgageRate": 3,
"mortgageAmortization": 25,
"closingDate": "2023-09-13",
"maturityDate": "2028-09-13",
"purposeID": 0,
"paymentFrequencyID": 3,
"private": false,
"rateTypeID": 0,
"fixed": true,
"mortgageTerm": 60,
"isCommercialDeal": false,
"firstTimeBuyer": true,
"readyForCompliance": false,
"complianceConfirmed": false,
"complianceStatusID": 0
}
]
Status | Schema |
---|---|
200 OK | array(Deal) |
Deal
Name | Type | Description |
---|---|---|
posSystemId | integer(int32) | PoS system |
brokerNetwork | string nullable | Broker network |
firmCode | string nullable | Firm code |
licenseeId | string nullable | Agent tenant code (Licensee Id) |
officeName | string nullable | Agent office name |
organizationName | string nullable | Firm name (organization) |
expertUsername | string nullable | Agent's expert username |
expertProfileId | string nullable | Agent's Expert profile Id |
username | string nullable | Agent's username |
linkId | string nullable | Agent's Link ID |
agentName | string nullable | Agent name |
agentID | string(uuid) nullable | Unique agent identifier |
loanCode | string nullable | Loan code |
expertLoanCode | string nullable | Expert loan code |
submissionReferenceNumber | string nullable | Submission reference number (Application number) |
lenderReferenceNumber | string nullable | Lender reference number (Broker reference number) |
applicationDate | string(date-time) | Application date |
dateUpdated | string(date-time) nullable | Application update date |
lenderPaymentReceived | string(date-time) nullable | Lender payment received date |
creditBureau | string nullable | Credit bureau provider |
dealStatusID | integer(int32) nullable | Deal status |
importStatusID | integer(int32) nullable | Import status |
clientFirstName | string nullable | Client first name |
clientLastName | string nullable | Client last name |
clientDOB | string(date) nullable | Client date of birth |
clientPhone | string nullable | Client phone number |
clientEmail | string nullable | Client email address |
coClientFirstName | string nullable | Co-client first name |
coClientLastName | string nullable | Co-client last name |
coClientDOB | string(date) nullable | Co-client date of birth |
coClientPhone | string nullable | Co-client phone number |
coClientEmail | string nullable | Co-client email address |
streetNumber | string nullable | Subject property address street number |
unitNumber | string nullable | Subject property address unit number |
streetName | string nullable | Subject property address street name |
streetType | string nullable | Subject property address street type |
streetTypeID |
StreetType nullable | |
streetDirection | string nullable | Subject property address street direction |
city | string nullable | Subject property address city |
province | string nullable | Subject property address province |
postalCode | string nullable | Subject property address postal code |
mortgagePositionID | integer(int32) nullable | Mortgage position |
lenderID | string nullable | Lender code |
lenderName | string nullable | Lender name |
fundedAmount | number(double) nullable | Funded amount |
mortgageRate | number(double) nullable | Mortgage rate |
mortgageAmortization | integer(int32) nullable | Mortgage amortization |
closingDate | string(date) nullable | Closing date |
maturityDate | string(date) nullable | Maturity date |
purposeID | integer(int32) nullable | Mortgage purpose |
paymentFrequencyID | integer(int32) nullable | Payment frequency |
mortgageType | integer(int32) nullable | Mortgage type |
private | boolean nullable | Private mortgage |
rateTypeID | integer(int32) nullable | Rate type |
fixed | boolean nullable | Fixed rate |
mortgageTerm | integer(int32) nullable | Mortgage term |
isCommercialDeal | boolean nullable | Is commercial deal? |
firstTimeBuyer | boolean nullable | First-time home buyer |
agentRemovedDateTimeUTC | string(date-time) nullable | Agent removed timestamp (UTC) |
isConnectCompliance | boolean nullable | Is Connect Compliance? |
readyForCompliance | boolean nullable | Ready for compliance |
complianceConfirmed | boolean nullable | Compliance confirmed |
complianceStatusID | integer(int32) nullable | Compliance status |
complianceStatusUpdateDateTimeUTC | string(date-time) nullable | Compliance status update timestamp (UTC) |
Enumerations
FilterMode
Values | Description |
---|---|
0 | Submittable |
1 | Not Imported |
2 | All |
StreetType
Values | Description |
---|---|
1 | Avenue |
2 | Boulevard |
3 | Circle |
4 | Crescent |
5 | Drive |
6 | Gate |
7 | Highway |
8 | Lane |
9 | Line |
10 | Road |
11 | Route |
12 | Street |
13 | Terrace |
14 | Trail |
15 | Way |
16 | Common |
17 | Court |
18 | Green |
19 | Manor |
20 | Place |
21 | Rise |
22 | Landing |
23 | Bay |
24 | Close |
25 | Link |
26 | Mews |
27 | View |
28 | Quay |
29 | Square |
30 | Abbey |
31 | Acres |
32 | Alley |
33 | Autoroute |
34 | Beach |
35 | Bend |
36 | By Pass |
37 | Byway |
38 | Campus |
39 | Cape |
40 | Centre |
41 | Chase |
42 | Circuit |
43 | Concession |
44 | Corners |
45 | Crossing |
46 | Culde Sac |
47 | Cove |
48 | Dale |
49 | Dell |
50 | Diversion |
51 | Downs |
52 | End |
53 | Estates |
54 | Expressway |
55 | Extension |
56 | Farm |
57 | Field |
58 | Forest |
59 | Freeway |
60 | Front |
61 | Gardens |
62 | Glade |
63 | Glen |
64 | Grounds |
65 | Grove |
66 | Harbour |
67 | Heights |
68 | Highlands |
69 | Hill |
70 | Hollow |
71 | Impasse |
72 | Island |
73 | Key |
74 | Knoll |
75 | Limits |
76 | Lookout |
77 | Loop |
78 | Mall |
79 | Maze |
80 | Meadow |
81 | Moor |
82 | Mount |
83 | Mountain |
84 | Orchard |
85 | Parade |
86 | Park |
87 | Parkway |
88 | Passage |
89 | Path |
90 | Pathway |
91 | Pines |
92 | Plaza |
93 | Point |
94 | Port |
95 | Private |
96 | Promenade |
97 | Range |
98 | Ridge |
99 | Row |
100 | Run |
101 | Subdivision |
102 | Thicket |
103 | Towers |
104 | Townline |
105 | Turnabout |
106 | Vale |
107 | Village |
108 | Vista |
109 | Walk |
110 | Wharf |
111 | Wood |
112 | Heath |
113 | Inlet |
114 | Plateau |
115 | Ramp |
116 | Villas |
117 | Wynd |
315 | Meadows |