Add Users

POST /v2/users/add

Add Users

cURL

curl --request POST \
  --url https://api.velt.dev/v2/users/add \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "createOrganization": true,
    "documentId": "<string>",
    "createDocument": true,
    "folderId": "<string>",
    "createFolder": true,
    "users": [
      {}
    ]
  }
}
'

{
  "result": {
    "status": "success",
    "message": "User(s) processed successfully.",
    "data": {
      "yourUserId1": {
        "success": true,
        "id": "4c250058149d6c9fb8c894c9ef29c790",
        "message": "User added."
      }
    }
  }
}

Use this API to add Users to:

1. Organization: This will provide them access to all the documents in the organization unless the document has restricted access type. It will also show users in the contact list of the organization.
2. Folder: This will provide them access to all the documents in the folder. If you pass the folderId, then the users will be added to the folder and not the organization.
3. Document: This will provide them access to the specified document. It will also show users in the contact list of the document. If you pass the documentId, then the users will be added to the document and not the organization or folder.

• If organization does not exist, it will be created.
• If you provide documentId or folderId, then the users will only be added at that level and not at the organization level. To also add users at the organization level, you will need to call this API again with only the organizationId.
• If User’s initial is not provided in the User object, then it will be automatically created using the name field.

Access Control

• Set accessRole to viewer (read-only) or editor (read/write) on each resource to define the user’s capabilities for that resource.
• accessRole can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change accessRole.
• Relevant endpoints: /v2/users/add, /v2/users/update, /v2/auth/permissions/add, /v2/auth/generate_token.
• See the Access Control overview for concepts and detailed guidance.

See the Access Control overview for concepts and detailed guidance.

Endpoint

POST https://api.velt.dev/v2/users/add

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

organizationId · string · required

Organization ID

createOrganization · boolean

If set to true, a new organization will be created (if it doesn’t exist) before users are added.

documentId · string

Document ID. Provide this if you want to add users to a specific document.

createDocument · boolean

If set to true and documentId is provided but doesn’t exist, a new document will be created before users are added.

folderId · string

Folder ID. Provide this if you want to add users to a specific folder. Either provide documentId or folderId.

createFolder · boolean

If set to true and folderId is provided but doesn’t exist, a new folder will be created before users are added.

users · User[] · required

Array of User objects.

Example Requests

1. Add users to a specific organization

Editor

{
  "data": {
    "organizationId": "yourOrganizationId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "[e-mail]",
        "accessRole": "editor"
      }
    ]
  }
}

Viewer

{
  "data": {
    "organizationId": "yourOrganizationId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "[e-mail]",
        "accessRole": "viewer"
      }
    ]
  }
}

2. Add users to a specific document within an organization

Editor

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "[e-mail]",
        "accessRole": "editor"
      }
    ]
  }
}

Viewer

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "[e-mail]",
        "accessRole": "viewer"
      }
    ]
  }
}

3. Add users to a specific folder within an organization

Editor

{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "[e-mail]",
        "accessRole": "editor"
      }
    ]
  }
}

Viewer

{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId",
    "users": [
      {
        "userId": "yourUserId1",
        "name": "User Name",
        "email": "[e-mail]",
        "accessRole": "viewer"
      }
    ]
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "User(s) processed successfully.",
    "data": {
      "yourUserId1": {
        "success": true,
        "id": "4c250058149d6c9fb8c894c9ef29c790",
        "message": "User added."
      }
    }
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "success",
    "message": "User(s) processed successfully.",
    "data": {
      "yourUserId1": {
        "success": true,
        "id": "4c250058149d6c9fb8c894c9ef29c790",
        "message": "User added."
      }
    }
  }
}