Overview
The FastTrack-FCU (FT FCU) API is designed to allow FastTrack Partners with easy access to data about the tenants they are assisting, including entitlements, contacts, and notes.
This document provides business use cases with walkthroughs for several example endpoint requests.
For a complete list of API endpoints refer to the following knowledge article FCU: FastTrack API Partner Integration Overview.
Partner Data
- Tenant ID
- Account Information about all users who will be able to access Authentication Certificate
- User/Account Token Information. See security overview.
- Any CORS headers you wish us to validate against.
Security Overview
All partners will be granted access to a certificate that allows them to authenticate at a high level with the API.
Certificates will be accessible via our Partner Management site which is available to the admin users you specify. We require the name and email address as linked to your AD for the admin users to access the site. The URLs for the management site are as follows:
- Testing: https://management.uat.fttoolingapi.microsoft.com/
- Production: https://management.prod.fttoolingapi.microsoft.com/
Once a certificate is downloaded, send the certificate upon each request to the API.
End User Token
If you provide direct interaction with the API to your end users, we strongly encourage you to integrate your tokens with the API. With this integration, we will validate your end user tokens and track individual user activities for forensic purposes, if needed. If you wish to enable this integration we will need the following information:
- The Tenant the users will come from.
- The unique identifier of the user in the token (usually sub).
- If you want us to validate the token or just track the end user.
Once provided, we will configure the system to accept a Bearer token on all API calls along with the standard certificate authentication.
Privacy
As stated in the FastTrack Partner Community Terms and Conditions, to participate in the Program, a partner must have entered into the Microsoft Cloud Partner Program Agreement (“Microsoft Cloud Partner Network Program”) with Microsoft. This agreement describes the Privacy and Data Protection policies that must be followed, covering customer and personal data.
URI
The API is a standard REST formatted API accessible at prod.partner.fttoolingapi.microsoft.com. All endpoints are predicated by a version number and API details. We are currently in a V1.1 state, so all calls will be for ftop/v1.1/api/…
For example: https://prod.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/timezones
Base URLS are as follows:
- UAT: https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/
- PROD: https://prod.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/
Rate Limits
The API rate limits activity to 600 calls per minute, per identifiable user (or without user token info, per IP address).
Errors
All error responses will return with a standard response code in the header, and additional error detail information in the following format:
{
ErrorStatus: (400, 500, etc.)
DependencyType: “SQL Server”, "Azure Search", "Dynamics", "Redis", "Internal"
DependencyOwner: "FTR CPOR Team", "FT_FCU API Team", "V3 Team"
DependencyErrorCode: Optional field containing structured error code that the dependency puts out.
Message: A descriptive message about the error that has occurred.
}
The DependencyErrorCode is additional debugging details about the error, in a simple string format. However, in the case of 400 errors, the debugging details will contain structured JSON with details about which input fields are invalid and a message about why they were invalid.
Example:
{
"errors": {
"Email": [
"Invalid email address provided"
],
"ContactTypeId": [
"Contact Type is Required"
]
},
"errorStatus": 400,
"message": "One or more validation errors occurred."
}
This is a list of standard HTTP 4xx and 5xx error codes and meanings:
- 400: Bad request
- 401: Unauthorized
- 403: Forbidden
- 404: Not found
- 405: Method not allowed
- 406: Not acceptable
- 408: Request timeout
- 409: Conflict
- 412: Precondition failed
- 429: Too many requests
- 500: Internal server error
- 501: Not implemented
- 502: Bad gateway
- 503: Service unavailable
- 504: Gateway timeout
Sample GET Request (Python)
The following code is a GET request example in Python. The outcome of this example is that all sample method requests/responses will not include a particular language and will follow HTTP REST standards.
import requests
# Replace the dummy file path with the actual path to the authentication certificate:
certificate_path = '/path/to/certificate.pem'
# Set the URL for the GET request:
url = 'https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/timezones'
# Set the headers for the GET request, including the JWT and CORS headers:
headers = {
'Authorization': 'Bearer <JWT token>',
'Origin': 'https://example.com',
}
# Load the authentication certificate:
with open(certificate_path, 'rb') as f:
certificate = f.read()
# Send the GET request with the certificate and headers:
response = requests.get(url, headers=headers, cert=certificate)
# Print the response content
print(response.content)
API Endpoints
For a complete list of API endpoints, click here. More details on endpoints use, review the Scenarios section, which covers typical scenarios that the API would require.
Scenarios: Tenants and Referral Details
Getting tenants with a claimed workload
Scenario: Retrieve a list of tenants that has at least one claimed workload. This scenario is a basic way to retrieve tenants’ details in an object to flow into your CRM systems.
REST Request
Request Syntax
| Method | Request URI |
| GET | {baseURI}/partnerTenants |
URI Parameter(s)
None
Request Body
None
Request Example (HTTP)
The following is an example of an HTTP request. Note: For headers, see the header section.
GET https://uat.partner.fttoolingapi.microsoft.com/ftop/v1/api/partnerTenants HTTP/1.1
REST Response
If successful, the response body should contain the details of all the tenants and claimed workloads for the tenant. Note: The tenants unclaimed workloads are not output.
Response Example (HTTP)
Status: 200 OK
{
“count”: 2,
“hasMore”: false,
“items”: [
{
“tenantId”: “123e4567-e89b-12d3-a456-426655440000”,
“tpid”: 123,
“name”: “Dummy Tenant 1”,
“claimedWorkloads”: [
{
“id”: 456,
“name”: “Dummy Workload 1”
},
{
“id”: 789,
“name”: “Dummy Workload 2”
}
]
},
{
“tenantId”: “98765432-10ab-cdef-0123-456789abcdef”,
“tpid”: 456,
“name”: “Dummy Tenant 2”,
“claimedWorkloads”: [
{
“id”: 123,
“name”: “Dummy Workload 3”
}
]
}
]
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information
Getting partner referrals
Scenario: Retrieve a list of any referrals currently being offered to you, including the tenant and any notes associated with the referral. This scenario is a basic way to obtain referral details in an object to flow into your CRM system.
REST Request
Request Syntax
| Method | Request URI |
| GET | {baseURI}/partnerReferrals |
URI Parameter(s)
| Parameter | Type | Description |
| Page | Int, query, default 1, OPTIONAL | This is a query parameter that defines the current page of data.
|
| pageSize | Int, query, default 25, OPTIONAL | This is a query parameter that delineates the number of entries to be included on a page.
Example: |
Request Body
None
Request Example (HTTP)
The following is an example of an HTTP request.
GET
https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/partnerReferrals?page=2&pageSize=10 HTTP/1.1
REST Response
The response body will contain the referrals associated with your account, including all tenant details and any workloads (claimed and unclaimed) associated with the referral and/or tenant
Response Example (HTTP)
Status: 200 OK
{
“count”: 3,
“hasMore”: false,
“items”: [
{
“id”: 1,
“created”: “2021-01-01T00:00:00Z”,
“tenantId”: “123e4567-e89b-12d3-a456-426655440000”,
“tenantName”: “Dummy Tenant 1”,
“tenantDomain”: “dummytenant1.com”,
“workloads”: [
{
“id”: 1,
“name”: “Dummy Workload 1”,
“claimed”: true
},
{
“id”: 2,
“name”: “Dummy Workload 2”,
“claimed”: false
}
]
},
{
“id”: 2,
“created”: “2021-01-02T00:00:00Z”,
“tenantId”: “98765432-10ab-cdef-0123-456789abcdef”,
“tenantName”: “Dummy Tenant 2”,
“tenantDomain”: “dummytenant2.com”,
“workloads”: [
{
“id”: 3,
“name”: “Dummy Workload 3”,
“claimed”: true
}
]
},
{
“id”: 3,
“created”: “2021-01-03T00:00:00Z”,
“tenantId”: 98765432-10ab-cdef-0123-996789abcdef,
“tenantName”: Dummy Tenant 3,
“tenantDomain”: dummytenant3.com,
“workloads”: [
{
“id”: 4,
“name”: “Dummy Workload 4”,
“claimed”: false
}
]
}
]
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Get a tenant's Entitlement Status Record for multiple services
Scenario: Retrieve the entitlement status records for multiple services within a tenant. This scenario is important because it will surface the license and/or entitlement information into your CRM. This can help inform field employees (subject to data privacy/sharing policies as stated by Microsoft) of the tenant’s status.
REST Request
REST Syntax
| Method | Request URI |
| GET | {baseURL}/tenants/{tenantId}/services/entitlements |
URI Parameter(s)
| Parameter | Type | Description |
| tenantID | string-uuid, path | The customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {11tenantId} in the URI path. |
| serviceIDs | Array[integer], query | This is a query parameter with the list of serviceIDs (see services endpoint) that will filter the request. Only the entitlement details for these serviceIDs will be returned.
|
Request Body
None
Request Example (HTTP)
The following is an example HTTP request. This only covers the HTTP request and method.
GET https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/tenants/c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/services/entitlements? serviceIds=1234&serviceIds=9876 HTTP/1.1
REST Response
If successful, the body of the response body will contain the entitlement status details of the collection of services within the tenant.
Response Example (HTTP)
Status: 200 OK
[
{
“serviceIntentId”: “123e4567-e89b-12d3-a456-426655440000”,
“l1”: {
“id”: “123e4567-e89b-12d3-a456-426655441111”,
“name”: “Service 1”
},
“id”: “123e4567-e89b-12d3-a456-426655442222”,
“name”: “Entitlement Status 1”,
“l2”: {
“id”: “123e4567-e89b-12d3-a456-426655443333”,
“name”: “Subservice 1”
},
“l3”: {
“id”: “123e4567-e89b-12d3-a456-426655444444”,
“name”: “Subsubservice 1”
},
“entitlementCount”: 100,
“targetDate”: “2022-01-01T00:00:00Z”,
“owner”: “John Doe”,
“nextActionDate”: “2021-12-01T00:00:00Z”,
“notes”: “This is a note.”
},
{
“serviceIntentId”: “456e4567-e89b-12d3-a456-426655440000”,
“l1”: {
“id”: “456e4567-e89b-12d3-a456-426655441111”,
“name”: “Service 1”
},
“id”: “456e4567-e89b-12d3-a456-426655442222”,
“name”: “Entitlement Status 1”,
“l2”: {
“id”: “456e4567-e89b-12d3-a456-426655443333”,
“name”: “Subservice 1”
},
“l3”: {
“id”: “456e4567-e89b-12d3-a456-426655444444”,
“name”: “Subsubservice 1”
},
“entitlementCount”: 50,
“targetDate”: “2022-01-01T00:00:00Z”,
“owner”: “Jane Doe”,
“nextActionDate”: “2021-12-01T00:00:00Z”,
“notes”: “This is a note.”
}
]
Response success and error codes
Each response comes with an HTTP status code that indicates the success or failure and additional debugging information.
Update service intent for a particular entitlement service
Scenario: Entitlement statuses are meant to capture customer service intent. It is critical to update this data. This method will allow your organization to easily update service intent via the CRM. Note: Consider creative “triggers” for this PATCH method from your CRM, depending on how users typically capture customer notes/feedback.
REST Request
Request Syntax
| Method | Request URI |
| PATCH | {baseURL}/tenants/{tenantId}/services/{serviceId}/entitlements |
URI Parameter(s)
| Parameter | Type | Description |
| tenantID | string-uuid, path | The customer tenantID, which can be pulled from the partnerTenants endpoint. This substitutes the {tenantId} in the URI path. |
| serviceID | integer, path | The serviceID that can be pulled from the services/frp endpoint. This substitutes the {serviceId} in the URI path. |
Request Body
| Name | Type | Updatable | Description |
| serviceIntentID | string-uuid | No | Identifier for a particular status record. To add an entitlement status that doesn’t exist, either don’t provide the serviceIntentId or pass it in as an empty guid. |
| L1id | string-uuid | Yes | Level 1 status for a set of entitlements. L1 values must be unique for all records in a particular service. E.g., there cannot be two records of 25 entitlements “In Progress,” there should be a single “In Progress” record with 50 entitlements. |
| L2id | string-uuid, nullable | Yes | Level 2 status for a set of entitlements |
| L3id | string-uuid, nullable | Yes | Level 3 status/engineering reason for a set of entitlements. |
| entitlementCount | Integer | Yes | Entitlement count. Note, while this is updatable, there is a unique rule – the sum of all entitlement counts must equal the total number of seats for the service which you can discover from the tenants/services/maxEntitlements endpoint. To remove an existing status, pass in a 0 entitlement seat count. |
| targetDate | string, datetime, nullable | Yes | Target start date for entitlement status |
| owner | string, nullable | Yes | Status owner |
| nextActionDate | string, nullable | Yes | Next action date for entitlement status |
| Notes | string | Yes | Notes relating to entitlement status |
Important: There are few unique rules for this request. First is that L1 values must be unique for all records in a particular service. E.g., there cannot be two records of 25 entitlements “In Progress,” there should be a single “In Progress” record with 50 entitlements. Additionally, the sum of all entitlement counts must equal the total number of seats for the service which you can discover from the tenants/services/maxEntitlements endpoint. To add an entitlement status that doesn’t exist, either don’t provide the serviceIntentId or pass it in as an empty guid. To remove an existing status, pass in a 0 entitlement seat count.
Request Example (HTTP)
See below an example HTTP request. This only covers the HTTP request and method.
PATCH https://uat.partner.fttoolingapi.microsoft.com/ftop/v1/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/services/1234/entitlements HTTP/1.1
{
"serviceIntentId": "c1b9d6c6-6d8c-4b6e-8a0e-8f9c7b1a5c6c",
"l1id": "In Progress",
"l2id": null,
"l3id": null,
"entitlementCount": 5,
"targetDate": "2022-01-01T00:00:00Z",
"owner": "John Doe",
"nextActionDate": "2022-01-15T00:00:00Z",
"notes": "This is a sample note"
}
REST Response
If successful, the body of the response will contain the entitlement status details of the collection of services within the tenant.
Response Example (HTTP)
Status: 200 OK
[
{
"serviceIntentId": "c1b9d6c6-6d8c-4b6e-8a0e-8f9c7b1a5c6c",
"l1": {
"id": "In Progress",
"name": "Sample L1 Name"
},
"l2": null,
"l3": null,
"entitlementCount": 5,
"targetDate": "2022-01-01T00:00:00Z",
"owner": "John Doe",
"nextActionDate": "2022-01-15T00:00:00Z",
"notes": "This is a sample note"
}
]
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Get contacts for a claimed tenant or referral
Scenario: Entitlement statuses are meant to capture customer service intent. It is critical to update this data. This method will allow your organization to easily update service intent via the CRM. Note: Consider creative “triggers” for this PATCH method from your CRM, depending on how users typically capture customer notes/feedback.
REST Request
REST Syntax
| Method | Request URI |
| PATCH | {baseURL}/tenants/{tenantId}/services/{serviceid}/entitlements |
URI Parameter(s)
| Parmeter | Type | Description |
| tenantID | string-uuid, path | The customer tenantID, which can be pulled from the partnerTenants endpoint. This substitutes the {tenantid} in the URI path. |
| serviceID | integer, path | The serviceId that can be pulled from the services/frp endpoint. This substitutes the {serviceId} in the URI path. |
Request Body
| Name | Type | Updatable | Description |
| serviceIntentID | string-uuid | string-uuid | Identifier for a particular status record. To add an entitlement status that doesn’t exist, either don’t provide the serviceIntentId or pass it in as an empty guid. |
| L1i | string-uuid | Yes | Level 1 status for a set of entitlements. L1 values must be unique for all records in a particular service. E.g., there cannot be two records of 25 entitlements “In Progress,” there should be a single “In Progress” record with 50 entitlements. |
| L2id | string-uuid/nullable | Yes | Level 2 status for a set of entitlements |
| L3id | string-uuid/nullable | Yes | Level 3 status/engineering reason for a set of entitlements |
| entitlementCount | Interger | Yes | Entitlement count. Note: While this is updatable, there is a unique rule – the sum of all entitlement counts must equal the total number of seats for the service which you can discover from the tenants/services/maxEntitlements endpoint. To remove an existing status, pass in a 0 entitlement seat count. |
| targetDate | string, datetime, nullable | Yes | Target start date for entitlement status |
| owner | string, nullable | Yes | Status owner |
| nextActionDate | string, nullable | Yes | Next action date for entitlement status |
| notes | string | Yes | Notes relating to entitlement status |
Important: There are few unique rules for this request. First is that L1 values must be unique for all records in a particular service. E.g., there cannot be two records of 25 entitlements “In Progress,” there should be a single “In Progress” record with 50 entitlements. Additionally, the sum of all entitlement counts must equal the total number of seats for the service which you can discover from the tenants/services/maxEntitlements endpoint. To add an entitlement status that doesn’t exist, either don’t provide the serviceIntentId or pass it in as an empty guid. To remove an existing status, pass in a 0 entitlement seat count.
Request Example (HTTP)
See below an example HTTP request. This only covers the HTTP request and method.
PATCH https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/services/1234/entitlements HTTP/1.1
{
"serviceIntentId": "c1b9d6c6-6d8c-4b6e-8a0e-8f9c7b1a5c6c",
"l1id": "In Progress",
"l2id": null,
"l3id": null,
"entitlementCount": 5,
"targetDate": "2022-01-01T00:00:00Z",
"owner": "John Doe",
"nextActionDate": "2022-01-15T00:00:00Z",
"notes": "This is a sample note"
}
REST Response
If successful, the body of the response will contain the entitlement status details of the collection of services within the tenant.
Response Example (HTTP)
Status: 200 OK
[
{
"serviceIntentId": "c1b9d6c6-6d8c-4b6e-8a0e-8f9c7b1a5c6c",
"l1": {
"id": "In Progress",
"name": "Sample L1 Name"
},
"l2": null,
"l3": null,
"entitlementCount": 5,
"targetDate": "2022-01-01T00:00:00Z",
"owner": "John Doe",
"nextActionDate": "2022-01-15T00:00:00Z",
"notes": "This is a sample note"
}
]
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Get contacts for a claimed tenant or referral
Scenario: Retrieve contacts for a claimed tenant or a tenant associated via a referral. This is a basic way to retrieve contacts for a singular tenant (that has a claimed workload) or a referral (which can have unclaimed workloads). Consider looking at the partnerTenants/contacts endpoint for retrieving contacts for multiple tenants. The tenant-specific contact endpoint is covered because it provides the rfaid distinction.
REST Request
Request Syntax
| Method | Request URI |
| GET | {baseURL}/tenants/{tenantId}/contacts |
URI Parameter(s)
| Parameter | Type | Description |
| tenantID | string-uuid, path | The customer tenantID, which can be pulled from the partnerTenants endpoint. This substitutes the {tenantId} in the URI path. |
| rfaID | integer, query, OPTIONAL | This is a query parameter that allows retrieval of contacts where the tenant is associated via a referral (rfaID can be retrieved via PartnerReferrals endpoint). The rfaID appears at the end of the URI. Example: …/contacts?rfaid=1234 |
| contactTypeID | Integer, query, OPTIONAL | This is a query parameter that filters for a specific contact type ID (contact type ID can be retrieved via contactTypes endpoint endpoint). This rfaID appears at the end of the URI. |
| page | Int, query, default 1, OPTIONAL | This is a query parameter that defines the current page of data. |
| pageSize | Int, query, default 25, OPTIONAL | This is a query parameter that delineates the number of entries to be included in a page. |
Request Body
None
Request Example (HTTP)
See the following example HTTP request.
GET https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/contacts?rfaid=1234 HTTP/1.1
REST Response
If successful, the body of the response should contain all the details for the contact(s) associated with the tenant and/or rfaid requested.
Response Example (HTTP)
Status: 200 OK
{
"rfaId": 1234,
"count": 1,
"hasMore": false,
"items": [
{
"contactId": "123e4567-e89b-12d3-a456-426655440000",
"tenantId": "c4b8d7a6-f9e6-4f6d-8c8e-1a1f4e6b9e3f",
"name": "John Doe",
"email": "johndoe@example.com",
"phone": "+1-555-555-5555",
"managerName": "Jane Smith",
"managerEmail": "janesmith@example.com",
"title": "IT administrator",
"isEngaged": true,
"isFastTrackContact": false,
"evidence": "Some evidence",
"surveyEligible": true,
"approvedSurvey": "Survey A",
"note": "Some note",
"created": "2022-01-01T00:00:00Z",
"createdBy": "Jane Smith",
"modified": "2022-01-01T00:00:00Z",
"modifiedBy": "John Doe",
"timezone": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "Eastern Standard Time"
},
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "Some name",
"countryRegion": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "United States"
},
"adminType": {
"id": "123",
"name": "Some admin type"
},
"surveyLanguage": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "English"
},
"contactType": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"name": "Some contact type"
},
"skillTypes": [
{
"id": 1,
"name": "Skill Type A"
},
{
"id": 2,
"name": "Skill Type B"
}
],
"services": [
{
"id": 1,
"name": "Service A"
},
{
"id": 2,
"name": "Service B"
}
]
}
]
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Create a contact
Scenario: Create a contact for a tenant. This allows you to send contact details back to the FCU when added into your CRM within the appropriate tenant.
REST Request
REST Syntax
| Method | Request URI |
| POST | {baseURL}/tenants/{tenantId}/contacts |
URI Parameter(s)
| Parameter | Type | Description |
| tenantID | string-uuid, path | The customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {tenantId} in the URI path. |
Request Body
| Name | Type | Required | Description |
| Name | string | Yes | Contact first and last name |
| string, nullable | Yes | Contact email | |
| phone | string, nullable | No | Contact phone number |
| managerName | string, nullable | No | First and last name of the contact's manager |
| managerEmail | string, nullable | No | Email of the contact's manager |
| title | string, nullable | Yes | Contact job title |
| isEngaged | Boolean, nullable | No | Engaged flag |
| isFastTrackContact | Boolean, nullable | No | FastTrack flag |
| evidence | string, nullable | No | |
| surveyEligible | Boolean, nullable | Yes | Flag for if contact is eligible for a survey |
| approvedSurvey | string, nullable | No | |
| note | string, nullable | No | Any relevant notes on the contact |
| timeZoneID | string - uuid, nullable | No | ID for the timezone (see Timezones endopoint) in which the contact operates |
| countryRegionID | string - uuid, nullable | Yes | ID for the country/region (see countryRegions endpoint) in which contact operates |
| adminTypeID | integer, nullable | No | ID for the admin user type for a contact (see adminTypes endpoint) |
| surveyLanguageID | string - uuid, nullable | Yes | ID for the survey language of contact (see surveyLanguages endpoint) |
| contactTypeID | integer | Yes | contact type ID (contact type ID that can be retrieved via contactTypes endpoint endpoint) |
| skillTypes | Array[integer], nullable | No | Integer array of skillTypeIDs (see skillTypes endpoint) |
| services | Array[integer], nullable | Yes | Interger array of serviceIDs (see services endpoint) |
Request Example (HTTP)
See the following for an example HTTP request. This only covers the HTTP request and method.
POST https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/contacts HTTP/1.1
{
"name": "John Doe",
"email": "johndoe@example.com",
"phone": "123-456-7890",
"managerName": "Jane Smith",
"managerEmail": "janesmith@example.com",
"title": "Manager",
"isEngaged": true,
"isFastTrackContact": false,
"evidence": "some evidence",
"surveyEligible": true,
"approvedSurvey": "some approved survey",
"note": "some note",
"timeZoneId": "12345678-1234-1234-1234-123456789abc",
"countryRegionId": "12345678-1234-1234-1234-123456789abc",
"adminTypeId": 1,
"surveyLanguageId": "12345678-1234-1234-1234-123456789abc",
"contactTypeId": 2,
"skillTypes": [1, 2, 3],
"services": [4, 5, 6]
}
REST Response
If successful, the response body should contain all the details for the contact that was just created.
Response Example (HTTP)
Status: 200 OK
{
"contactId": "a7b7d7a6f9e64f6d8c8e1a1f4e6b9e3c",
"tenantId": "c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f",
"name": "John Doe",
"email": "johndoe@example.com",
"phone": "123-456-7890",
"managerName": "Jane Smith",
"managerEmail": "janesmith@example.com",
"title": "Manager",
"isEngaged": true,
"isFastTrackContact": false,
"evidence": "some evidence",
"surveyEligible": true,
"approvedSurvey": "some approved survey",
"note": "some note",
"created": "2021-07-01T12:00:00Z",
"createdBy": "user123",
"modified": "2021-07-01T12:00:00Z",
"modifiedBy": "user456",
"timezone": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "Pacific Standard Time"
},
"id": "12345678-1234-1234-1234-123456789abc",
"name": "United States",
"countryRegion": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "California"
},
"adminType": {
"id": "1",
"name": "Admin Type 1"
},
"surveyLanguage": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "English"
},
"contactType": {
"id": "2",
"name": "Contact Type 2"
},
"skillTypes": [
{
"id": 1,
"name": "Skill Type 1"
},
{
"id": 2,
"name": "Skill Type 2"
},
{
"id": 3,
"name": "Skill Type 3"
}
],
"services": [
{
"id": 4,
"name": "Service 4"
},
{
"id": 5,
"name": "Service 5"
},
{
"id": 6,
"name": "Service 6"
}
]
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Update a Contact
Scenario: When making changes to contacts in your CRM, this method will allow you to change the contact with a valid contactID (no tenant input required).
REST Request
Request Syntax
| Method | Request URI |
| PATCH | {baseURL}/contacts/{contactId} |
URI Parameter(s)
| Parameter | Type | Description |
| contactID | string-uuid, path | The contactID that is going to be updated. This substitutes the {contactId} in the URI path. |
Request Body
| Name | Type | Required | Description |
| name | string | Yes | Contact full name |
| string, nullable | Yes | Contact email | |
| phone | string, nullable | Yes | Contact phone number |
| managerName | string, nullable | No | Full name of contact's manager |
| managerEmail | string, nullable | No | Emil of the of contact's manager |
| title | string, nullable | Yes | Contact job title |
| isEngaged | Boolean, nullable | No | Engaged flag |
| isFastTrackContact | Boolean, nullable | No | FastTrack flag |
| evidence | string, nullable | No | |
| surveyEligible | Boolean, nullable flag | Yes | Flag for if contact is eligible for a survey |
| approvedSurvey | string, nullable flag | No | |
| note | string, nullable | No | Any relevant notes on the contact |
| timeZoneID | string - uuid, nullable | No | ID for the timezone, (see Timezones endpoint) in which the contact operates |
| countryRegionID | string - uuid, nullable | Yes | ID for the country/region (see country/Regions endpoint) in which contact operates |
| adminTypeID | integer, nullable | No | ID for the admin user type for a contact (see adminTypes endpoint) |
| surveyLanguageID | string - uuid, nullable | Yes | ID for the survey language of contact (see surveyLanguages endpoint) |
| contactTypeID | integer | Yes | contact type ID (contact type ID can be retrieved via contactType endpoint) |
| skillTypes | Array[integer], nullable | No | Integer array of skillTypeIDs (see skillTypes endpoint) |
| services | Array[integer], nullable | Yes | Integer array of servicesIDs (see services endpoint) |
Request Example (HTTP)
See below an example HTTP request. This only covers the HTTP request and method.
POST https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/contacts c4b8d7a6f9e64f6d8c8e1a1f4e6b9e77 HTTP/1.1
{
"name": "John Doe",
"email": "johndoe@example.com",
"phone": "123-456-7890",
"managerName": "Jane Smith",
"managerEmail": "janesmith@example.com",
"title": "Manager",
"isEngaged": true,
"isFastTrackContact": false,
"evidence": "some evidence",
"surveyEligible": true,
"approvedSurvey": "some approved survey",
"note": "some note",
"timeZoneId": "12345678-1234-1234-1234-123456789abc",
"countryRegionId": "12345678-1234-1234-1234-123456789abc",
"adminTypeId": 1,
"surveyLanguageId": "12345678-1234-1234-1234-123456789abc",
"contactTypeId": 2,
"skillTypes": [1, 2, 3],
"services": [4, 5, 6]
}
REST Response
If successful, the body of the response should contain all the details for the contact that was just edited.
Response Example (HTTP)
Status: 200 OK
{
"contactId": "c4b8d7a6f9e64f6d8c8e1a1f4e6b9e77",
"tenantId": "c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f",
"name": "John Doe",
"email": "johndoe@example.com",
"phone": "123-456-7890",
"managerName": "Jane Smith",
"managerEmail": "janesmith@example.com",
"title": "Manager",
"isEngaged": true,
"isFastTrackContact": false,
"evidence": "some evidence",
"surveyEligible": true,
"approvedSurvey": "some approved survey",
"note": "some note",
"created": "2021-07-01T12:00:00Z",
"createdBy": "user123",
"modified": "2021-07-01T12:00:00Z",
"modifiedBy": "user456",
"timezone": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "Pacific Standard Time"
},
"id": "12345678-1234-1234-1234-123456789abc",
"name": "United States",
"countryRegion": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "California"
},
"adminType": {
"id": "1",
"name": "Admin Type 1"
},
"surveyLanguage": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "English"
},
"contactType": {
"id": "2",
"name": "Contact Type 2"
},
"skillTypes": [
{
"id": 1,
"name": "Skill Type 1"
},
{
"id": 2,
"name": "Skill Type 2"
},
{
"id": 3,
"name": "Skill Type 3"
}
],
"services": [
{
"id": 4,
"name": "Service 4"
},
{
"id": 5,
"name": "Service 5"
},
{
"id": 6,
"name": "Service 6"
}
]
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Get notes for a claimed tenant or a referral
Scenario: Retrieve notes for a claimed tenant or a tenant associated via a referral. This is the method to use to remain in sync with the FCU on notes for a tenant with a claimed workload, or a tenant in a referral, that may not have a claimed workload.
REST Request
Request Syntax
| Method | Request URI |
| GET | {baseURL}/tenants/{tenantId}/notes |
URI Paramter(s)
| Parameter | Type | Description |
| tenantID | string-uuid, path | The customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {tenantId} in the URI path. |
| noteCategory | integer, query, default 1 | Filters result based on a particular noteCategoryID, see noteCategories endpoint. |
| rfaID | integer, query, OPTIONAL | This is a query parameter that allows retrieval of notes where the tenant is associated via a referral (rfaID can be retrieved via PartnerReferrals endpoint).
|
| orderByCreated | string, query, OPTIONAL | This is a query parameter that orders the results based on 2 available values: Ascending, Descending Example: |
| page | Int, query, default 1, OPTIONAL | This is a query parameter that defines the current page of data |
| pageSize | Int, query, default 25, OPTIONAL | This is a query parameter that delineates the number of pages to be included in a page |
Request Body
None
Request Example (HTTP)
See below an example HTTP request.
GET https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/notes?noteCategory=1 HTTP/1.1
REST Response
If successful, the response body should contain all the details for the note(s) associated with the tenant and/or rfaid requested.
Response Example (HTTP)
Status: 200 OK
{
"rfaId": null,
"count": 3,
"hasMore": false,
"tenantId": "c4b8d7a6-f9e6-4f6d-8c8e-1a1f4e6b9e3f",
"tenantName": "Example Tenant",
"items": [
{
"text": "This is the first note",
"author": "John Doe",
"created": "2021-08-01T12:00:00Z",
"noteCategory": {
"id": 1,
"name": "Engagement Management"
}
},
{
"text": "This is the second note",
"author": "Jane Smith",
"created": "2021-08-02T10:30:00Z",
"noteCategory": {
"id": 1,
"name": "Engagement Management"
}
},
{
"text": "This is the third note",
"author": "John Doe",
"created": "2021-08-03T14:15:00Z",
"noteCategory": {
"id": 1,
"name": " Engagement Management"
}
}
]
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.
Create notes for a claimed tenant or a referral
Scenario: Create notes for a claimed tenant or a tenant associated via a referral. This method should be triggered when a note is entered within your CRM, posting the same note to the FCU.
REST Request
Request Syntax
| Method | Request URI |
| POST | {baseURL}/tenants/{tenantId}/notes |
URI Parameter(s)
| Parameter | Type | Description |
| tenantID | string - uuid, path | The customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {tenantId} in the URI path. |
Request Body
| Name | Type | Description |
| text | string, nullable | The text that describes the note (character limit = 1,048,576) |
| noteCategoryID | integer | Categorizes the note, see the NoteCategoryID endpoint for full list |
Request Example (HTTP)
See the following HTTP request example.
POST https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.1/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/notes HTTP/1.1
{
"text": "This is a new note",
"noteCategoryId": 1
}
REST Response
If successful, the body of the response should contain all the details for the note(s) that was just created.
Response Example (HTTP)
Status: 200 OK
{
"text": "This is a new note",
"author": null,
"created": "2021-08-10T09:30:00Z",
"noteCategory": {
"id": 1,
"name": "Engagement Management"
}
}
Response success and error codes
Each response comes with an HTTP status code that indicates success or failure and additional debugging information.