Views:
In this article: Overview | Partner Data | Security Overview | End User Token | Privacy | URIRate Limits | Errors | Sample GET Request (Python) | API Endpoints | Scenarios: Tenants and Referral Details

 

Overview

The FastTrack Partner Experience (FT FPX) 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 FPX: 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:

Once a certificate is downloaded, send the certificate upon each request to the API.

Note: Certificates are required to be rotated every 120 days. Email notifications will be sent to individuals with download permissions 30 days prior to the expiration date to ensure sufficient time for replacement.   

FTOP API Certificate download

 

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.

URL

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.2 state, so all calls will be for ftop/v1.2/api/…
For example: https://prod.partner.fttoolingapi.microsoft.com/ftop/v1.2/api/timezones
Base URLS are as follows:

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.2/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

MethodRequest 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.2/api/partnerTenants HTTP/1.2

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

MethodRequest URI
GET{baseURI}/partnerReferrals

URI Parameter(s)

ParameterTypeDescription
PageInt, query, default 1, OPTIONAL

This is a query parameter that defines the current page of data.


This will appear at the end of the URI.


Example:
…/api/partnerReferrals?page=2

pageSizeInt, query, default 25, OPTIONAL

This is a query parameter that delineates the number of entries to be included on a page.


This will appear at the end of the URI

Example:
…/api/partnerReferrals?page=2&pageSize=10

Request Body

None

Request Example (HTTP)

The following is an example of an HTTP request.


GET

https://uat.partner.fttoolingapi.microsoft.com/ftop/v1.2/api/partnerReferrals?page=2&pageSize=10 HTTP/1.2
 

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

MethodRequest URI
GET{baseURL}/tenants/{tenantId}/services/entitlements

URI Parameter(s)

ParameterTypeDescription
tenantIDstring-uuid, pathThe customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {11tenantId} in the URI path.
serviceIDsArray[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.


These serviceIDs appear at the end of the URI.


Example:
…/services/entitlements?serviceIds=1234&serviceIds=9876

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.2/api/tenants/c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/services/entitlements? serviceIds=1234&serviceIds=9876 HTTP/1.2

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

MethodRequest URI
PATCH{baseURL}/tenants/{tenantId}/services/{serviceId}/entitlements

URI Parameter(s)

ParameterTypeDescription
tenantIDstring-uuid, pathThe customer tenantID, which can be pulled from the partnerTenants endpoint. This substitutes the {tenantId} in the URI path.
serviceIDinteger, pathThe serviceID that can be pulled from the services/frp endpoint. This substitutes the {serviceId} in the URI path.

 

Request Body

NameTypeUpdatableDescription
serviceIntentIDstring-uuidNoIdentifier 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.
L1idstring-uuidYesLevel 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.
L2idstring-uuid, nullableYesLevel 2 status for a set of entitlements
L3idstring-uuid, nullableYesLevel 3 status/engineering reason for a set of entitlements.
entitlementCountIntegerYesEntitlement 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. 
targetDatestring, datetime, nullableYesTarget start date for entitlement status
ownerstring, nullableYesStatus owner
nextActionDatestring, nullableYesNext action date for entitlement status
NotesstringYesNotes 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.2/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/services/1234/entitlements HTTP/1.2

{

    "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

MethodRequest URI
PATCH{baseURL}/tenants/{tenantId}/services/{serviceid}/entitlements

URI Parameter(s)

ParmeterTypeDescription
tenantIDstring-uuid, pathThe customer tenantID, which can be pulled from the partnerTenants endpoint. This substitutes the {tenantid} in the URI path.
serviceIDinteger, pathThe serviceId that can be pulled from the services/frp endpoint. This substitutes the {serviceId} in the URI path.

 

Request Body

NameTypeUpdatableDescription
serviceIntentIDstring-uuidstring-uuidIdentifier 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.
L1istring-uuidYesLevel 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.
L2idstring-uuid/nullableYesLevel 2 status for a set of entitlements
L3idstring-uuid/nullableYesLevel 3 status/engineering reason for a set of entitlements
entitlementCountIntergerYesEntitlement 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.
targetDatestring, datetime, nullableYesTarget start date for entitlement status
ownerstring, nullableYesStatus owner
nextActionDatestring, nullableYesNext action date for entitlement status
notesstringYesNotes 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.2/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/services/1234/entitlements HTTP/1.2

{

    "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

MethodRequest URI
GET{baseURL}/tenants/{tenantId}/contacts

URI Parameter(s)

ParameterTypeDescription
tenantIDstring-uuid, pathThe customer tenantID, which can be pulled from the partnerTenants endpoint. This substitutes the {tenantId} in the URI path.
rfaIDinteger, query, OPTIONALThis 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
contactTypeIDInteger, 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.
Example:
…/contacts?contacttypeid=1234

pageInt, query, default 1, OPTIONALThis is a query parameter that defines the current page of data.
pageSizeInt, query, default 25, OPTIONALThis 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.2/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/contacts?rfaid=1234 HTTP/1.2

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

MethodRequest URI
POST{baseURL}/tenants/{tenantId}/contacts

URI Parameter(s)

ParameterTypeDescription
tenantIDstring-uuid, pathThe customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {tenantId} in the URI path.

Request Body

NameTypeRequiredDescription
NamestringYesContact first and last name
emailstring, nullableYesContact email
phonestring, nullableNoContact phone number
managerNamestring, nullableNoFirst and last name of the contact's manager
managerEmailstring, nullableNoEmail of the contact's manager
titlestring, nullableYesContact job title
isEngagedBoolean, nullableNoEngaged flag
isFastTrackContactBoolean, nullableNoFastTrack flag
evidencestring, nullable No 
surveyEligibleBoolean, nullableYesFlag for if contact is eligible for a survey
approvedSurveystring, nullableNo 
notestring, nullableNoAny relevant notes on the contact
timeZoneIDstring - uuid, nullableNoID for the timezone (see Timezones endopoint) in which the contact operates
countryRegionIDstring - uuid, nullableYesID for the country/region (see countryRegions endpoint) in which contact operates
adminTypeIDinteger, nullableNoID for the admin user type for a contact (see adminTypes endpoint)
surveyLanguageIDstring - uuid, nullableYesID for the survey language of contact (see surveyLanguages endpoint)
contactTypeIDintegerYescontact type ID (contact type ID that can be retrieved via contactTypes endpoint endpoint)
skillTypesArray[integer], nullableNoInteger array of skillTypeIDs (see skillTypes endpoint)
servicesArray[integer], nullableYesInterger 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.2/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/contacts HTTP/1.2


{

    "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

MethodRequest URI
PATCH{baseURL}/contacts/{contactId}

URI Parameter(s)

ParameterTypeDescription
contactIDstring-uuid, pathThe contactID that is going to be updated. This substitutes the {contactId} in the URI path.

Request Body

NameTypeRequiredDescription
namestringYesContact full name
emailstring, nullableYesContact email
phonestring, nullableYesContact phone number
managerNamestring, nullableNoFull name of contact's manager
managerEmailstring, nullableNoEmil of the of contact's manager
titlestring, nullableYesContact job title
isEngagedBoolean, nullableNoEngaged flag
isFastTrackContactBoolean, nullableNoFastTrack flag
evidencestring, nullableNo 
surveyEligibleBoolean, nullable flagYesFlag for if contact is eligible for a survey
approvedSurveystring, nullable flagNo 
notestring, nullableNoAny relevant notes on the contact
timeZoneIDstring - uuid, nullableNoID for the timezone, (see Timezones endpoint) in which the contact operates
countryRegionIDstring - uuid, nullableYesID for the country/region (see country/Regions endpoint) in which contact operates
adminTypeIDinteger, nullableNoID for the admin user type for a contact (see adminTypes endpoint)
surveyLanguageIDstring - uuid, nullableYesID for the survey language of contact (see surveyLanguages endpoint)
contactTypeIDintegerYescontact type ID (contact type ID can be retrieved via contactType endpoint)
skillTypesArray[integer], nullableNoInteger array of skillTypeIDs (see skillTypes endpoint)
servicesArray[integer], nullableYesInteger 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.2/api/contacts c4b8d7a6f9e64f6d8c8e1a1f4e6b9e77 HTTP/1.2

{

    "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

MethodRequest URI
GET{baseURL}/tenants/{tenantId}/notes

URI Paramter(s)

ParameterTypeDescription
tenantIDstring-uuid, pathThe customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {tenantId} in the URI path.
noteCategoryinteger, query, default 1Filters result based on a particular noteCategoryID, see noteCategories endpoint.
rfaIDinteger, 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).


This rfaID appears at the end of the URI
Example:
…/notes?rfaid=1234

orderByCreatedstring, query, OPTIONAL

This is a query parameter that orders the results based on 2 available values: Ascending, Descending

Example:
…/notes?orderByCreated=Ascending

pageInt, query, default 1, OPTIONALThis is a query parameter that defines the current page of data
pageSizeInt, query, default 25, OPTIONALThis 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.2/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/notes?noteCategory=1 HTTP/1.2

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

MethodRequest URI
POST{baseURL}/tenants/{tenantId}/notes

URI Parameter(s)

ParameterTypeDescription
tenantIDstring - uuid, pathThe customer tenantID, which can be pulled from partnerTenants endpoint. This substitutes the {tenantId} in the URI path.

Request Body

NameTypeDescription
textstring, nullableThe text that describes the note (character limit = 1,048,576)
noteCategoryIDintegerCategorizes 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.2/api/tenants/ c4b8d7a6f9e64f6d8c8e1a1f4e6b9e3f/notes HTTP/1.2

{

    "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.