Create a referral

post

https://msft.cosell.tackle.io/api/referrals

Create a co-sell IP referral and submit it to Microsoft
Partner Center. The shape of the request and the side effect
depend on the optional tackle-operation-id header (default
createIPReferral); see the header description for the full
list of sub-operations and when to use each. Returns
202 Accepted immediately with a Tackle referral ID and a
requestId you can correlate to subsequent events via
listReferralEvents.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

The name of the Referral

companyWebsite

string

URL of the customer organization. Captured by Tackle for context and not forwarded to Microsoft Partner Center.

crmId

string

Identifier of the parent CRM record this referral is linked to
(typically a Salesforce 18-character Opportunity ID). 15-character
Salesforce IDs are accepted and normalized to 18 characters.

crmOrgId

string

Organization (tenant) ID of the CRM system. Required in multi-org CRM setups to disambiguate which org the crmId belongs to.

mpnId

string

required

The MPN ID of the partner

campaignId

string

Marketing campaign ID

dealSensitivity

string

enum

required

The sensitivity of the deal based on the selected customer.

Allowed:

customerProfile

object

required

Customer contact information. Required.

consent

object

required

Consent flags around sharing information with other organizations and allowing them to contact users. Required.

details

object

required

Customer details, notes, deal value, currency closing date. Required.

team

array of objects

required

Represents users in the organizations that are involved in the partner engagement.

team*

inviteContexts

array of objects

Include to invite Microsoft or another organization to the deal.

inviteContexts

Headers

tackle-operation-id

string

enum

The unique identifier for the operation to perform when creating the referral. The header is optional; when omitted, it defaults to createIPReferral.

createIPReferral (default): Create a new outbound IP co-sell referral and submit it to Microsoft Partner Center.
createDraftIPReferral: Save a draft referral in Tackle without submitting it to Microsoft. The draft can later be submitted via POST /api/referrals/{referral_id} with tackle-operation-id: createIPReferralFromDraft.
cloneIPReferral: Create a new referral by cloning an existing one. The request body must include trackingInfo.clonedFromOpportunityId referencing the source referral.
createInboundIPReferral: Test-environment-only. Simulate Microsoft sharing an inbound IP co-sell referral with the ISV without making any real Partner Center calls, so customers can exercise the inbound-referral receive flow end-to-end in a test environment. Production vendors should not use this value; in production environments the request is accepted but no referral is created.

Allowed:

Responses

500

An unexpected error occurred while processing the request. The response body is
empty.

Language

Credentials

Bearer

MTM JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

202Accepted

400The request was malformed or could not be processed. Returned when the JSON body cannot be parsed, when a required field is missing, when an unsupported tackle-operation-id is supplied, or when a referenced CRM ID is invalid.

401The request did not include a valid Tackle MTM access token, so no principal could be established. The response body is {} — the message field is omitted.

403The authenticated principal does not have permission to perform this operation. The response body is {} — the message field is omitted.

409The request conflicts with an existing resource. For example, attempting to create or accept a referral with a CRM ID that is already linked to another co-sell opportunity.