Transfer a Prospect

When a prospect exists within a club network, they are linked to their original club. This documentation explains the prospect migration process, which enables controlled mobility of prospects within a club network.

Retrouvez ce scénario dans notre collection Bruno

Gagnez du temps dans votre implémentation en observant l'enchaînement des appels et en récupérant les requêtes directement depuis Bruno.

Migration Principle

Since a prospect record belongs to club A, if that same prospect wants to go to club B, they must start a migration process. From the prospect's point of view, this process is:

• Start a migration request
• Receive a confirmation code by SMS
• Enter the confirmation code

Warning

The network headers to use for each call vary. The rule is to always use network headers from where the migration is intended to go: the destination club.

• [Source club] Identify the contact you want to migrate
• [Destination club] Initialize the migration
• [Destination club] Validate the migration
• [Destination club] Retrieve the updated contact in their new club

Initialize Migration

Prospect migration works by sending an SMS to the contact, containing a code that must be used in the next step.

Example

curl --request POST \
  --url https://gateway.prod.gravitee.stadline.tech/{{env}}/{{clientToken}}/contact_migration_requests \
  --header 'Authorization: Bearer {{jwtToken}}' \
  --header 'X-Gravitee-Api-Key: {{apiKey}}' \
  --header 'content-type: application/json' \
  --header 'x-user-club-id: {{clubTwoId}}' \ -- Destination club
  --header 'x-user-network-node-id: {{clubTwoNetworkNodeId}}' \ -- Destination club
  --data '{
  "contactId":"{{contactId}}", -- Contact identifier
  "clubId":"{{clubTwoId}}", -- Destination club
  "disableNetwork": true // Important for avoiding any issues with discovering entities across networks
}'

Response 201 Created

{  
   "@context":"\/clientToken\/contexts\/SignatureRequest",
   v------ Migration request identifier ------v
   "@id":"\/clientToken\/signature_requests\/455434",
   "@type":"SignatureRequest",
  // ...
}

Complete the Migration Process

Once the SMS is received, the application orchestrating the migration must collect the code from the targeted contact and complete the signature process by validating this code.

POST /{clientToken}/signature_requests/{signatureRequestId}/transitions

parameter	description	example
signatureRequestId	Identifier of the signature process created previously	3451
transition	Desired transition type. Possible values are validate or cancel	validate
code	Validation code received by SMS	1234

Example

curl --request POST \
  --url https://gateway.prod.gravitee.stadline.tech/{{env}}/{{clientToken}}/signature_requests/{{id}}/transitions \
  --header 'Authorization: Bearer {{jwtToken}}' \
  --header 'X-Gravitee-Api-Key: {{apiKey}}' \
  --header 'content-type: application/json' \
  --header 'x-user-club-id: {{clubOneId}}' \ -- Destination club
  --header 'x-user-network-node-id: {{clubOneNetworkNodeId}}' \ -- Destination club
  --data '{
    "transition": "validate",
    "code": "949875" -- Code received by SMS
    "disableNetwork": true // Important for avoiding any issues with discovering entities across networks
}'

Response 201 Created

{
  "@context": "/demoapi/contexts/SignatureRequest",
  "@id": "/demoapi/signature_requests/23716",
  "@type": "SignatureRequest",
  "state": "validated",
  // ...
  "targetIds": [
    "/demoapi/clubs/1357"
  ],
   v------ Identifier of the contact created in the destination club ------v
  "resultTargetId": "/demoapi/contacts/2973829"
}

Referenced Errors

400: Bad Request La ressource \"/{clientToken}/contacts/{id}\" n'existe pas.

This is related to data-sharing rules between clubs configured in a network. You are currently operating for a club that does not have the required rights to access the contact record to migrate.

Solution: If you are authenticated with client_credentials and provide node headers, operate from a level above the club node.

400: Bad Request api.error.contact.migration.club-not-valid

The target club is not valid. This occurs when migration is requested to the contact's current club.

Solution: Review the target club.

400: Bad Request api.error.contact.migration.contact-not-valid

The contact cannot be transferred. This occurs when the contact status is neither prospect nor former client.

Solution: Review the contact.