Transferring a Prospect
When a prospect exists within a club chain, they are initially tied to their original club. The following documentation explains the prospect migration process, which enables controlled mobility of prospects within a chain of clubs.
Migration Overview
Since a prospect record belongs to Club A, if the same prospect wishes to transfer to Club B, a migration process must be initiated. From the prospect's point of view, the process involves:
- Initiating a migration request
- Receiving a confirmation code via SMS
- Entering the confirmation code to complete the transfer
Initiating the Migration
The prospect migration process begins by sending an SMS to the contact. This SMS contains a confirmation code required in the next step.
POST /{clientToken}/contact_migration_requests
| Parameter | Description | Example |
|---|---|---|
clubId | IRI of the destination club | /{clientToken}/clubs/1 |
contactId | IRI of the prospect to be migrated | /{clientToken}/contacts/12345 |
Example
POST /{clientToken}/contact_migration_requests
Body
{
"clubId": "/{clientToken}/clubs/1",
"contactId": "/{clientToken}/contacts/12345"
}Response 201 Created
{
"@context":"/clientToken/contexts/SignatureRequest",
"@id":"/clientToken/signature_requests/455434", <-------- Migration identifier
"@type":"SignatureRequest",
// ...
}Completing the Migration Process
Once the SMS has been received, the application handling the migration must collect the code from the targeted contact and finalize the process by validating the code.
POST /{clientToken}/signature_requests/{signatureRequestId}/transitions
| Parameter | Description | Example |
|---|---|---|
signatureRequestId | ID of the previously created signature process | 3451 |
transition | Desired transition type. Possible values are validate or cancel | validate |
code | Validation code received by SMS | 1234 |
Example
POST /{clientToken}/signature_requests/3451/transitions
Body
{
"transition": "validate",
"code": "1234"
}Response 201 Created
Referenced Errors
400 : Bad Request Resource "/{clientToken}/contacts/{id}" does not exist.
This error is related to the data-sharing configuration between clubs within a chain.
You are currently operating on behalf of a club that does not have the rights to access the contact record targeted for migration.
Solution: If you are authenticated using client_credentials and providing node headers, operate from a higher-level node than the club's node.
400 : Bad Request api.error.contact.migration.club-not-valid
The target club is not valid. This typically occurs when you attempt to migrate the contact to their current club.
Solution: Review and correct the target club.
400 : Bad Request api.error.contact.migration.contact-not-valid
The contact is not eligible for transfer. This happens when the contact's status is neither prospect nor former member.
Solution: Review and update the contact being migrated.