# Vendor API documentation This API is designed for vendor clients of Swapcard. Each request must contain a valid API key in the `Authorization` header. For support, please contact me at [geoffrey@swapcard.com](mailto:geoffrey@swapcard.com). Use the base endpoint depending if you want to test the API or for real usage: + To use the real API in production, use: `https://vnd-api.swapcard.com` + To test the API, use: `https://apidev.swapcard.com/vnd` --- ### Post a user or attendee Creates a new user on Swapcard, and automatically adds him to the event if your key is linked to an event. ```shell POST /v1/users Content-Type: application/json Authorization: Bearer YjY1NzA5NTM5MmIyNzEzZTRhYjY1NWNlMjVjYmYwZGUxMzFlNjBhN2JmYjA1MGUwYzk4NzA1MjcyOTA5YjRkYw ``` #### The body The required fields are: + first_name + last_name + email + language (`fr` or `en`) ```json { "first_name": "Geoffrey", "last_name": "Thierry", "email": "geoffrey@swapcard.com", "password": "azerty", "job_title": "Technical Manager", "job_title_2": "VC", "company": "Swapcard", "keywords": ["Development", "API", "PHP"], "photo": "http://path/to/image", "mobile_phone": "+33 6 85 12 65 32", "landline_phone": "+33 9 26 12 51 23", "address": "46 rue René Clair", "zip_code": "75018", "city": "Paris", "language": "fr", "website_url": "https://www.swapcard.com", "biography": "This is my bio.", "metadata": { "badge_codes": ["12465885545112651"] } } ``` #### Response 201 In case the user didn't exist: ```json { "id": 123, "first_name": "Geoffrey", "last_name": "Thierry", "email": "geoffrey@swapcard.com", "job_title": "Technical Manager", "job_title_2": "VC", "company": "Swapcard", "keywords": ["Development", "API", "PHP"], "photo": "http://path/to/image", "mobile_phone": "+33 6 85 12 65 32", "landline_phone": "+33 9 26 12 51 23", "address": "46 rue René Clair", "zip_code": "75018", "city": "Paris", "website_url": "https://www.swapcard.com", "biography": "This is my bio.", "qrcode_url": "https://api.swapcard.com/public/images/abc123.png", "created_at": "2016-05-16T19:39:14+0200" } ``` #### Response 400 In case the user already exists (but he will still be added to your event): ```json { "status": 400, "message": "Validation failed", "errors": [ "email: This value is already used." ], "data": { "id": 123, "qrcode_url": "https://api.swapcard.com/public/images/abc123.png" } } ``` --- ### Join or leave a planning This endpoint allows you to add or remove users from a planning. You must use a Swapcard id as the id parameter, or your own id by adding an extra parameter `use_external`. ```shell PATCH /v1/plannings/A565E121F?use_external Content-Type: application/json Authorization: Bearer YjY1NzA5NTM5MmIyNzEzZTRhYjY1NWNlMjVjYmYwZGUxMzFlNjBhN2JmYjA1MGUwYzk4NzA1MjcyOTA5YjRkYw ``` #### The body You must send a list of operations in the top-level attribute `data`. Each operation must have: + An attribute `operation` (either `join` or `leave`). + An attribute `data` with an object containing two attributes `value` and `type`. + The type of an operation data must be one of `id`, `email`. + The value must be an array of values representing a user depending of the type you sent. ```json { "data": [ { "operation": "join", "data": { "value": [5412, 4541], "type": "id" } }, { "operation": "leave", "data": { "value": ["geoffrey@swapcard.com"], "type": "email" } } ] } ``` The response will contains successful and failed operations. If all operations fail, the status code will be `400` otherwise it will be `200`. #### Response 200 ```json { "success": [ {"operation": "join", "value": 4541} {"operation": "join", "value": "geoffrey@swapcard.com"} ], "errors": [ { "operation": "join", "value": 5412, "error_code": 400, "reason": "This user is already in this planning" } ] } ``` #### Response 400 ```json { "status": 400, "error_code": 20, "message": "All operations have failed", "errors": [ { "operation": "join", "value": 4541, "error_code": 404, "message": "This user does not exist" }, { "operation": "join", "value": "geoffrey@swapcard.com", "error_code": 403, "message": "You are not allowed to update this user" } ] } ```