Skip to main content

create-signup-request 

dci create-signup-request [body]

Starts a Cloud Intelligence trial signup for the organization owning the email domain. Idempotent per Idempotency-Key: a retried create returns the same request. Nothing is provisioned until the admin verifies the request. Human channels (console, web) additionally require a Cloudflare Turnstile token and an accepted Terms of Service version; the emailed 6-digit verification code is then the consent act. Agents should present consentUrl to the organization's admin and poll getSignupRequest. Existing accounts, customer domains and previous trials receive the same pending response as new organizations. Eligibility is evaluated after mailbox verification or authenticated human consent.

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

email (the organization admin's work email; free-mail and disposable addresses are rejected) and companyName are required, and so is --idempotency-key (1 to 256 characters). Retrying with the same key returns the same request instead of creating a second one. No authentication is needed.

Nothing is provisioned until the admin verifies the request. Present the returned consentUrl to the organization's admin, or enter the emailed code yourself with dci verify-signup-request, and poll dci get-signup-request until the request is completed. The human channels (console, web) also require a turnstileToken and termsConsent{version, accepted}; the default agent channel does not.

Conflicts return 409: the email or domain is already registered (the response carries signInUrl), a signup is already pending for it (the response carries signupRequestId), or the trial was already used.

Examples​

# Start a trial signup for the organization that owns the admin's work email domain.
dci create-signup-request --idempotency-key "$(uuidgen)" email: [email protected], companyName: "Example Corp"
Returns the signup request with its `id` (sr_ prefix), `status: pending_consent` and a `consentUrl`. The admin receives a 6-digit verification code by email.
# Identify the calling agent for attribution.
dci create-signup-request --idempotency-key <request-key> email: [email protected], companyName: "Example Corp", source{channel: agent, agentClient: "my-agent 1.0"}
# Create it from a JSON file, and capture the request ID for the follow-up calls.
dci create-signup-request --idempotency-key <request-key> --output json < signup.json | jq -r .id
# signup.json
{"email": "[email protected]", "companyName": "Example Corp"}

Request​

Content-Type: application/json

FieldTypeRequiredDescription
emailstring (email)yesWork email of the organization's admin. Free-mail and disposable addresses are rejected.
companyNamestringyes
sourceobjectAttribution. channel defaults to agent; console and web are the human channels.
source.channelstringOne of: "agent", "console", "web". Default: "agent".
source.agentClientstringName and version of the calling agent (agent channel).
source.campaignstring
source.utmSourcestring
source.utmMediumstring
source.utmCampaignstring
turnstileTokenstringCloudflare Turnstile response token. Required for the console and web channels.
termsConsentobjectTerms of Service acceptance. Required for the console and web channels.
termsConsent.versionstringyesTerms version shown to the requester; must be a version the API currently accepts, otherwise terms_version_outdated.
termsConsent.acceptedbooleanyes
Raw JSON schema
{
  "type": "object",
  "required": [
    "email",
    "companyName"
  ],
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 120,
      "description": "Work email of the organization's admin. Free-mail and disposable addresses are rejected."
    },
    "companyName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "source": {
      "type": "object",
      "description": "Attribution. channel defaults to agent; console and web are the human channels.",
      "properties": {
        "channel": {
          "type": "string",
          "enum": [
            "agent",
            "console",
            "web"
          ],
          "default": "agent"
        },
        "agentClient": {
          "type": "string",
          "maxLength": 120,
          "description": "Name and version of the calling agent (agent channel)."
        },
        "campaign": {
          "type": "string",
          "maxLength": 120
        },
        "utmSource": {
          "type": "string",
          "maxLength": 120
        },
        "utmMedium": {
          "type": "string",
          "maxLength": 120
        },
        "utmCampaign": {
          "type": "string",
          "maxLength": 120
        }
      }
    },
    "turnstileToken": {
      "type": "string",
      "maxLength": 2048,
      "description": "Cloudflare Turnstile response token. Required for the console and web channels."
    },
    "termsConsent": {
      "type": "object",
      "description": "Terms of Service acceptance. Required for the console and web channels.",
      "required": [
        "version",
        "accepted"
      ],
      "properties": {
        "version": {
          "type": "string",
          "description": "Terms version shown to the requester; must be a version the API currently accepts, otherwise terms_version_outdated."
        },
        "accepted": {
          "type": "boolean"
        }
      }
    }
  }
}

Output​

OK - an earlier request with the same Idempotency-Key was returned.

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

FieldTypeDescription
idstringPublic request id (sr_ prefix); an unguessable capability.
statusstringOne of: "pending_consent", "consented", "provisioning", "completed", "rejected", "expired", "failed".
channelstringOne of: "agent", "console", "web".
companyNamestringCompany name supplied at signup; shown on the console verification and completion pages.
consentUrlstring (uri)Page where the organization's admin verifies the request (pending_consent only).
activationTokenstringReturned once, by the verifySignupRequest call that performed the verification. Redeem it with createSignupSession after the request is completed.
resultTokenstringReturned only by successful verifySignupRequest. Send as Signup-Result-Token when polling this request to read its result. Valid for one hour; never returned by create, replay, resend or GET.
verificationobjectPresent while the request awaits the emailed code.
verification.requiredboolean
verification.expiresAtstring (date-time)
verification.resendAfterSecondsinteger
verification.sendsRemaininginteger
expiresAtstring (date-time)When an unverified request expires (pending_consent only).
pollAfterSecondsintegerSuggested polling interval while the request is not terminal.
customerIdstringThe provisioned tenant (completed only).
consoleUrlstring (uri)
signInUrlstring (uri)Page where the admin signs into the new tenant (completed only).
tierstringTrial tier name (trial).
trialEndDatestring (date-time)
nextStepsarray of string
reasonobjectWhy a terminal request did not complete.
reason.codestring
reason.detailstring
reason.retryableboolean
Raw JSON schema
{
  "type": "object",
  "description": "Redacted public view of a signup request. Never includes the admin email, the verification code or the idempotency key.",
  "required": [
    "id",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Public request id (sr_ prefix); an unguessable capability."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending_consent",
        "consented",
        "provisioning",
        "completed",
        "rejected",
        "expired",
        "failed"
      ]
    },
    "channel": {
      "type": "string",
      "enum": [
        "agent",
        "console",
        "web"
      ]
    },
    "companyName": {
      "type": "string",
      "description": "Company name supplied at signup; shown on the console verification and completion pages."
    },
    "consentUrl": {
      "type": "string",
      "format": "uri",
      "description": "Page where the organization's admin verifies the request (pending_consent only)."
    },
    "activationToken": {
      "type": "string",
      "description": "Returned once, by the verifySignupRequest call that performed the verification. Redeem it with createSignupSession after the request is completed."
    },
    "resultToken": {
      "type": "string",
      "description": "Returned only by successful verifySignupRequest. Send as Signup-Result-Token when polling this request to read its result. Valid for one hour; never returned by create, replay, resend or GET."
    },
    "verification": {
      "type": "object",
      "description": "Present while the request awaits the emailed code.",
      "properties": {
        "required": {
          "type": "boolean"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "resendAfterSeconds": {
          "type": "integer"
        },
        "sendsRemaining": {
          "type": "integer"
        }
      }
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "When an unverified request expires (pending_consent only)."
    },
    "pollAfterSeconds": {
      "type": "integer",
      "description": "Suggested polling interval while the request is not terminal."
    },
    "customerId": {
      "type": "string",
      "description": "The provisioned tenant (completed only)."
    },
    "consoleUrl": {
      "type": "string",
      "format": "uri"
    },
    "signInUrl": {
      "type": "string",
      "format": "uri",
      "description": "Page where the admin signs into the new tenant (completed only)."
    },
    "tier": {
      "type": "string",
      "description": "Trial tier name (trial)."
    },
    "trialEndDate": {
      "type": "string",
      "format": "date-time"
    },
    "nextSteps": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "reason": {
      "type": "object",
      "description": "Why a terminal request did not complete.",
      "properties": {
        "code": {
          "type": "string"
        },
        "detail": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      }
    }
  }
}

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 statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
42950RATE_LIMITEDToo many requests. Retryable — the CLI reports the server-provided delay.
50340API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: createsignuprequest