Create an account

Overview

Create a new account under your partner, with its owner. The owner gets a set-password welcome email automatically.

Use this when you onboard a new business. Add with_location=1 to also create its first location in the same call; for a single-location business that's the whole setup. To place the account under one of your sub-partners instead of directly under you, pass parent_company_id.

You'll need the business name and address (city_id, postal_code, industry), the owner's first name and email, a starting password for the owner, and the plan_id to assign. Optional: your own client_account_id, a billing reference, website, phones.

Returns the new account's id (accountId.value). The plan is linked, the owner is invited, and if with_location=1, the first location exists and is ready for review site connections.

Prerequisites

A Partner token. See Authentication.
A plan_id that is set up for your partner. See List your plans.
A city_id and an industry id (companyindustry_id).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/partner/account/create

Authentication

Partner token

The new account is created directly under your partner, or under parent_company_id when you send it.
parent_company_id must be inside your own account tree; otherwise 422.
plan_id must be one of the plans set up for your partner (or for the partner that parent_company_id belongs to); otherwise 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`name`	string	Yes	The account (business) name. Max 100 characters, no `<` or `>`.
`website`	string	No	The business website. Must be a valid URL.
`billing_id`	string	No	Your billing reference for the account. Max 100 characters, no `<` or `>`.
`client_account_id`	string	No	Your own id for the account. Max 100 characters, no `<` or `>`.
`phone`	string	No	The business phone. 9 to 15 characters.
`address`	string	Yes	Street address. Max 255 characters, no `<` or `>`.
`city_id`	integer	Yes	The city. Must be an existing city id.
`companyindustry_id`	integer	Yes	The industry. Must be an existing, active industry id.
`postal_code`	string	Yes	Postal code. 3 to 12 characters, no `<` or `>`.
`first_name`	string	Yes	The owner's first name. Max 100 characters.
`last_name`	string	No	The owner's last name. Max 100 characters.
`owner_email`	string	Yes	The owner's email address. Must not already belong to a user. The domain must accept mail (it's checked with a DNS lookup), so test domains like `example.com` are rejected with `422`.
`owner_phone`	string	No	The owner's phone. 9 to 15 characters.
`password`	string	Yes	The owner's starting password. 8 to 100 characters, with upper- and lowercase letters, a number and a symbol; no quotes, backslashes or spaces.
`plan_id`	integer	Yes	The plan to assign. Must be one of the plans set up for your partner.
`parent_company_id`	integer	No	Where to place the account: one of your sub-partners or another company in your account tree. Leave it out to create the account directly under your partner.
`with_location`	integer	No	`1` to also create the account's first location, on the same plan, from the account's name, address, phone and website. `0` or left out: no location.

Request payload

{
  "name": "Acme Brand",
  "website": "https://acmebrand.com",
  "billing_id": "BILL-001",
  "client_account_id": "ACC-001",
  "phone": "1234567890",
  "address": "1 George St",
  "city_id": 3243,
  "companyindustry_id": 37,
  "postal_code": "2000",
  "first_name": "Jane",
  "last_name": "Smith",
  "owner_email": "<owner-email>",
  "owner_phone": "9876543210",
  "password": "<your-password>",
  "plan_id": 36,
  "with_location": 0
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`Account has been created successfully!`
`accountId`	object	The new account.
`accountId.label`	string	The account's name. When you sent a `client_account_id`, it's added after a dash, e.g. `Acme Brand - ACC-001`.
`accountId.value`	integer	The new account's id. Use it as the account id in other calls.

Response payload

{
  "data": {
    "status": "success",
    "message": "Account has been created successfully!",
    "accountId": {
      "label": "Acme Brand - ACC-001",
      "value": 6021
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Required fields missing

{
  "message": "The name field is required. (and 8 more errors)",
  "errors": {
    "name": ["The name field is required."],
    "address": ["The address field is required."],
    "city_id": ["The city id field is required."],
    "companyindustry_id": ["Please select an industry for the account."],
    "postal_code": ["The postal code field is required."],
    "first_name": ["The first name field is required."],
    "owner_email": ["The owner email field is required."],
    "password": ["The password field is required."],
    "plan_id": ["The plan id field is required."]
  }
}

422 Plan not available

{
  "message": "The selected plan is not available for your account.",
  "errors": {
    "plan_id": ["The selected plan is not available for your account."]
  }
}

422 Parent outside your tree

{
  "message": "The selected parent company id does not belong to your company hierarchy.",
  "errors": {
    "parent_company_id": ["The selected parent company id does not belong to your company hierarchy."]
  }
}

422 Email rejected

The address is malformed, or its domain doesn't accept mail.

{
  "message": "The owner email field must be a valid email address.",
  "errors": {
    "owner_email": ["The owner email field must be a valid email address."]
  }
}

Status	Meaning
`200`	The account is created.
`401`	The token is missing, expired or invalid.
`422`	The request failed validation. The response names the fields.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/partner/account/create" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Acme Brand", "website": "https://acmebrand.com", "billing_id": "BILL-001", "client_account_id": "ACC-001", "phone": "1234567890", "address": "1 George St", "city_id": 3243, "companyindustry_id": 37, "postal_code": "2000", "first_name": "Jane", "last_name": "Smith", "owner_email": "<owner-email>", "owner_phone": "9876543210", "password": "<your-password>", "plan_id": 36, "with_location": 0}'