invite-user

dci invite-user [body]

Invites a new user to the organization with specified role and organization.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Examples

# Invite a user with a role; role IDs come from `dci list-roles`.
dci invite-user email: [email protected], roleId: <role-id>

# Fill in the name and job function as well.
dci invite-user email: [email protected], firstName: Jane, lastName: Doe, jobTitle: "Software / Ops Engineer", roleId: <role-id>

# Assign the user to an organization from a JSON file (organization IDs come from `dci list-organizations`).
dci invite-user < invite.json

# invite.json
{"email": "[email protected]", "roleId": "<role-id>", "organizationId": "<organization-id>"}

# Keep the new invite's ID for `resend-invite` or `cancel-invite`.
dci invite-user email: [email protected], roleId: <role-id> --fields user --output json

Request

Content-Type: application/json

Field	Type	Required	Description
email	string (email)	yes	The email address of the user.
firstName	string		The first name of the user being invited.
lastName	string		The last name of the user being invited.
jobTitle	string		The job function of the user being invited. One of: "Data Engineer / Data Analysts", "Executive Team", "Finance / Accounting", "Founder", "Legal / Purchasing", "Management", "Sales / Marketing", "Software / Ops Engineer".
roleId	string		The ID of the role to assign to the user.
organizationId	string		The ID of the organization to assign the user to.

Raw JSON schema

{
  "type": "object",
  "description": "Request body to invite a new user to the organization.",
  "required": [
    "email"
  ],
  "properties": {
    "email": {
      "type": "string",
      "description": "The email address of the user.",
      "format": "email"
    },
    "firstName": {
      "type": "string",
      "description": "The first name of the user being invited."
    },
    "lastName": {
      "type": "string",
      "description": "The last name of the user being invited."
    },
    "jobTitle": {
      "type": "string",
      "description": "The job function of the user being invited.",
      "enum": [
        "Data Engineer / Data Analysts",
        "Executive Team",
        "Finance / Accounting",
        "Founder",
        "Legal / Purchasing",
        "Management",
        "Sales / Marketing",
        "Software / Ops Engineer"
      ]
    },
    "roleId": {
      "type": "string",
      "description": "The ID of the role to assign to the user."
    },
    "organizationId": {
      "type": "string",
      "description": "The ID of the organization to assign the user to."
    }
  }
}

Output

Created - User invitation created successfully.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Field	Type	Description
message	string	Success message
user	object
user.id	string	The unique ID of the invited user.
user.email	string	The email address of the invited user.
user.firstName	string	The first name of the invited user, if provided during invitation.
user.lastName	string	The last name of the invited user, if provided during invitation.
user.displayName	string	The display name of the invited user, if provided during invitation.
user.jobTitle	string	The job function of the invited user, if provided during invitation.
user.roleId	string	The ID of the role assigned to the user.
user.organizationId	string	The ID of the organization assigned to the user.
user.status	string	The status of the user (invited) One of: "invited".

Raw JSON schema

{
  "type": "object",
  "description": "Response returned after creating a user invitation.",
  "properties": {
    "message": {
      "type": "string",
      "description": "Success message"
    },
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique ID of the invited user."
        },
        "email": {
          "type": "string",
          "description": "The email address of the invited user."
        },
        "firstName": {
          "type": "string",
          "description": "The first name of the invited user, if provided during invitation."
        },
        "lastName": {
          "type": "string",
          "description": "The last name of the invited user, if provided during invitation."
        },
        "displayName": {
          "type": "string",
          "description": "The display name of the invited user, if provided during invitation."
        },
        "jobTitle": {
          "type": "string",
          "description": "The job function of the invited user, if provided during invitation."
        },
        "roleId": {
          "type": "string",
          "description": "The ID of the role assigned to the user."
        },
        "organizationId": {
          "type": "string",
          "description": "The ID of the organization assigned to the user."
        },
        "status": {
          "type": "string",
          "description": "The status of the user (invited)",
          "enum": [
            "invited"
          ]
        }
      }
    }
  }
}

Errors

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping

HTTP status	Exit code	Error code	Meaning
400	30	VALIDATION_ERROR	The arguments or request body were rejected. Review the command's flags and payload.
401	10	AUTHENTICATION_FAILED	Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
403	11	PERMISSION_DENIED	The DoiT user or the active customer context does not have access.
500	40	API_SERVER_ERROR	The API failed to process the request. Retryable; contact DoiT support if it persists.

Related

• list-users — List users
• resend-invite — Resend invite
• cancel-invite — Cancel invite
• update-user — Update user
• list-roles — List roles
• API reference: POST /iam/v1/users/invite

Aliases: inviteuser