Confirm customer acceptance and create agreement for MCA using APIs

Important

This article pertains to an experience only available in CSP integration sandbox, launching April 11, 2025. The experience is targeted to become generally available on July 10, 2025.

Applies to: Partner Center

Doesn't apply to: Partner Center operated by 21Vianet | Partner Center for Microsoft Cloud for US Government

Partner Center currently supports confirming customer acceptance of the Microsoft Customer Agreement (MCA) only in the Microsoft public cloud. This article describes how to confirm or reconfirm customer acceptance of the MCA and then create the agreement for a particular customer. This information applies to Indirect Provider and Direct Bill CSP partners. Indirect Resellers can't use this experience.

Prerequisites

• Credentials as described in Partner Center authentication. This scenario only supports AppOnly authentication.

• Information about the user from the customer organization that accepted the MCA, including:

  • First name
  • Last name
  • Email address
  • Phone number (optional)
  • Company name

If the following values change for a customer, Partner Center allows you to create another agreement for that customer. The First name, Last name, Email address, and Phone number must differ. Otherwise, partners receive the following error code, due to a duplicate record being created.

{
"code": 600061,
"message": "A partner confirmed agreement already exists for the customer.",
"description": "A partner confirmed agreement already exists for the customer.",
"errorName": "PartnerConfirmedAgreementAlreadyExists",
"isRetryable": false,
"parameters": {},
"errorMessageExtended": "InternalErrorCode=600061"
}

Create Partner attestation and agreement creation using APIs

The enhanced attestation API helps partners create and manage customer attestations that they can embed within a checkout flow. Partners can then use the customer attestation to create an agreement for a particular customer.

To confirm or reconfirm customer acceptance of the MCA and then create an agreement for a customer:

1. Create a new attestation object (attestation ID) by using the Enhanced Customer Attestation API for a customer.

2. Construct the url of the embeddable component that can be used in any checkout flow to accept the MCA. You need to ensure that the customers see the MCA and accept the same using the parametrized link provided by Microsoft.

3. Create the agreement using Create agreement API using the attestation ID.

Using enhanced customer attestation API

Endpoint

POST https://api.partnercenter.microsoft.com/v{version}/attestations/enhanced

Description

Creates an attestation ID for a customer that can then be used to attest the MCA for that customer.

Authorization

• Requires authentication.

• Requires PartnerAuthorize(PartnerApiResource.PartnerConfirmation, ResourceAccess.Create).

Request Body

Field	Type	Required	Default	Validation	Description
country	string	Yes	"US"		Customer's country code (ISO 3166-1 alpha-2)
language	string	Yes	"en-US"		Preferred language for agreement
companyName	string	Yes			Name of the company accepting the agreement
signatoryFirstName	string	Yes			First name of the individual signing the agreement
signatoryLastName	string	Yes			Last name of the individual signing the agreement
emailAddress	string	Yes		Valid email format	Signatory's email address
phoneNumber	string	Yes			Signatory's phone number
expirationInMinutes	integer	No	60	5 to 10080	Expiration time in minutes for the attestation

Custom expiration feature

The expirationInMinutes parameter allows you to customize how long the attestation remains valid:

• Default: 60 minutes (one hour)
• Minimum: 5 minutes
• Maximum: 10,080 minutes (seven days)
• Behavior: The attestation will automatically expire and become inaccessible after the specified time

Response

Success Response (201 Created)

{"attestationId": "550e8400-e29b-41d4-a716-446655440000"}

Response Headers:

HTTP/1.1 201 Created

Location: /attestations/enhanced/550e8400-e29b-41d4-a716-446655440000

Content-Type: application/json

Error Responses:

400 Bad Request - Validation Error

{"type": "validation","title": "One or more validation errors occurred","status": 400,"errors": {"ExpirationInMinutes": ["ExpirationInMinutes must be between 5 minutes and 7 days (10,080 minutes)."]}}

400 Bad Request - Missing Required Fields

{"type": "validation","title": "One or more validation errors occurred","status": 400,"errors": {"CompanyName": ["The CompanyName field is required."],"EmailAddress": ["The EmailAddress field is required."]}}

401 Unauthorized

{"error": "unauthorized","error_description": "The access token is invalid or has expired"}

404 Not Found

{"error": "This API is not available for your partner type"}

Usage examples

Example 1: Basic attestation (Default one-hour expiration)

POST {baseUrl}/attestations/enhanced 

Content-Type: application/jsonAuthorization: Bearer {token} 
 
{ 
  "country": "US", 
  "language": "en-US",   
  "companyName": "Contoso Ltd", 
  "signatoryLastName": "Smith", 
  "signatoryFirstName": "John", 
  "emailAddress": "john.smith@contoso.com", 
  "phoneNumber": "+1-555-0123" 
}

Example 2: Quick attestation (30 minutes)

POST {baseUrl}/attestations/enhanced 

Content-Type: application/jsonAuthorization: Bearer {token} 
 
{ 
  "country": "US", 
  "language": "en-US",
  "companyName": "Quick Corp", 
  "signatoryLastName": "Fast", 
  "signatoryFirstName": "Lightning", 
  "emailAddress": "lightning@quickcorp.com", 
  "phoneNumber": "+1-555-0456", 
  "expirationInMinutes": 30 
}

Example 3: Extended attestation (three days)

POST {baseUrl}/attestations/enhanced 

Content-Type: application/jsonAuthorization: Bearer {token} 
 
{ 
  "country": "US", 
  "language": "en-US", 
  "companyName": "Extended Solutions Inc", 
  "signatoryLastName": "Patient", 
  "signatoryFirstName": "Very", 
  "emailAddress": "very.patient@extendedsolutions.ca", 
  "phoneNumber": "+1-555-0789", 
  "expirationInMinutes": 4320 
}

Using embeddable component

The AttestationId returned by the Enhanced Customer Attestation API can be used as a parameter in to the below mentioned link to show the MCA to the customer in an embeddable component. Partners need to ensure that the customers see the MCA and accept the same using the parametrized link provided by Microsoft.

Example of an embeddable iframe with the parametrized link

<iframe src="https://cdn.partner.microsoft.com/mca/?attestationid={id}"></iframe> 

The link renders the MCA agreement and contains an "Accept Agreement" button; selecting the same, calls a POST API that captures the customer's intent to accept the MCA. It's a prerequisite for partners to call Create Agreement API successfully.

Create Agreement API

Creates an agreement on behalf of a customer.

POST https://api.partnercenter.microsoft.com/v{version}/customers/{customer_id}/agreements

URI Parameters

Name	In	Required	Type	Description
customer_id	path	True	string	Customer ID
version	path	True	string

Request Header

Media Types: "application/json"

Name	Required	Type	Description
Authorization	True	string	Authorization Bearer token
ms-correlationid		string	Used for tracking requests internally. If a ms-correlationid isn't provided, the server generates a new one for each request
ms-cv		string	Used for tracking requests internally. If a ms-cv isn't provided, the server generates a new one for each request
ms-requestid		string	Used for idempotency of requests. If a ms-requestid isn't provided, the server generates a new one for each request

Request Body

Media Types: "application/json"

Name	Type	Description
agreement	Microsoft.Partner.Service.Customers.Contracts.V1.Agreement	Agreement

Responses

Name	Type	Description
200 OK	object	OK Media Types: "application/json", "text/json", "application/xml", "text/xml"
201 Created	Microsoft.Partner.Service.Customers.Contracts.V1.Agreement	The request was successful. The agreement is successfully created. Media Types: "application/json", "text/json", "application/xml", "text/xml"

Definitions

Name	Description
Microsoft.Partner.Service.Customers.Contracts.V1.Agreement
Microsoft.Partner.Service.Customers.Contracts.V1.Contact

Microsoft.Partner.Service.Customers.Contracts.V1.Agreement

Name	Type	Description
agreementLink	string
dateAgreed	string	The date when the customer accepted the agreement
primaryContact	Microsoft.Partner.Service.Customers.Contracts.V1.Contact	Information about the user from the customer organization who accepted the MCA, including: firstName, lastName, email, and phoneNumber (optional) Note: This field can be left blank if the attestationId is provided. If not left blank, the information here should match the specifications from the enhanced attestation document. No validation occurs on the primaryContact information shared here versus the information in the Enhanced Customer Attestation API. This field is required only if attestationId isn't provided, for example if a partner is using v1 or old API of attestation. For more information, see Enhanced Customer Attestation API in this article. See Example request to understand the payload.
templateId	string	Unique identifier of the agreement type accepted by the customer. You can obtain the templateId for MCA by retrieving the agreement metadata for MCA. See Get agreement metadata for MCA for details.
type	enum: - MicrosoftCloudAgreement - MicrosoftCustomerAgreement	Agreement type accepted by the customer. Use "MicrosoftCustomerAgreement" if customer accepted the MCA.
userId	string
attestationId (new)	guid	ID of the enhanced attestation, using the Enhanced Customer Attestation API.

Microsoft.Partner.Service.Customers.Contracts.V1.Contact

Name	Type	Description
email	string
firstName	string
lastName	string
phoneNumber	string

Example request payload

Sample payload when enhanced attestation API is used

{"userId": "80fdc6b6-ad7c-4783-be01-7b8002d2a949","attestationId": "d7cb60a6-b8d3-486a-b7f5-b17ef03d3427","templateId": "117a77b0-9360-443b-8795-c6dedc750cf9","dateAgreed": "2025-06-03T16:42:12","type": "MicrosoftCustomerAgreement"} 

In case the user wants to use the existing method of attestation (till it's deprecated) and not the new enhanced API then they can call the Create Agreement API with the primary contact details