The /1/learner/{learnerId}/transfer endpoint provides functionality to transfer a learner from one organization to another.

This will DELETE all authorizations for this learner

Beta API

NOTE: This API is currently in beta and applies only to iframe reseller API customers.

Request Headers

Key	Value	Example
User-Agent	`<company identifier>`	The exact value here is not important, but it should include something to identify your company
Accept	`application/json`
Authorization	`Bearer <your token>`	`Bearer 23142424`
Content-Type	`application/json`

Request Parameters

URL Parameters

learnerId (required): The ID of the learner to transfer (e.g., 98925)

Request Body

The request body should be a JSON object. Currently accepts an empty object {} for basic transfer operations.

{}

Code Examples

CURL

curl --location --request PATCH 'https://api-sandbox.vbmappapp.com/1/learner/1234/transfer' \
--header 'User-Agent: dmtd-rest-api' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{}'

Production Example

curl --location --request PATCH 'https://api.vbmappapp.com/1/learner/12312/transfer' \
--header 'User-Agent: your-company-identifier' \
--header 'Authorization: Bearer YOUR_PRODUCTION_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{}'

Example Response

Success Response (200 OK)

{
    "success": true,
    "message": "Learner transfer initiated successfully",
    "data": {
        "learnerId": 98925,
        "newOwner": "BeepBeepz",
        "transferDetails": {
            "transferId": "TRF-2025-98925-001",
            "initiatedAt": "2025-01-21T10:15:30.000000Z",
            "status": "completed",
            "assessmentIds": [
                "ASM-2025-001",
                "ASM-2025-002"
            ]
        },
        "learnerGroups": {
            "removed": [
                {
                    "id": 1440,
                    "name": "Previous Learner Group",
                    "description": "Reseller API authorized users for learner"
                }
            ],
            "added": [
                {
                    "id": 1,
                    "name": "New Learner Group",
                    "description": "Your organization's learner group"
                }
            ]
        },
        "authorizations": {
            "revoked": [
                {
                    "userId": 123,
                    "email": "[email protected]",
                    "name": "Previous Admin",
                    "role": "Admin",
                    "authorizedAt": "2024-12-01T08:00:00.000000Z",
                    "authorizedById": 456
                }
            ]
        }
    }
}

Error Responses

404 Not Found

{
    "success": false,
    "error": "Learner not found",
    "message": "No learner exists with ID 98925"
}

403 Forbidden

{
    "success": false,
    "error": "Unauthorized",
    "message": "You do not have permission to transfer this learner"
}

400 Bad Request

{
    "success": false,
    "error": "Invalid request",
    "message": "Learner is already associated with your organization"
}

500 Internal Server Error

{
    "success": false,
    "error": "Transfer failed",
    "message": "An error occurred during the transfer process. Please try again or contact support."
}

Notes

Authentication: Ensure you're using a valid Bearer token with appropriate permissions for learner transfers.
Sandbox Environment: Use https://api-sandbox.vbmappapp.com for testing before moving to production.
Production Environment: Use https://api.vbmappapp.com for live transfers.
Transfer Process: The transfer will:
- Remove the learner from their current organization's learner groups
- Revoke all existing user role authorizations for that learner
- Associate the learner with your organization
- Return assessment IDs associated with the transferred learner
Idempotency: Multiple transfer requests for the same learner to the same organization will return success but won't create duplicate transfers.

Rate Limiting

Maximum 100 transfer requests per hour per API token
Maximum 1000 transfer requests per day per organization

Support

For issues or questions regarding the learner transfer API, contact support.