# Add one location to the CreatoRain Network **Not live yet:** the v1 API and its hosts are not open. See [Sandbox](/get-started/sandbox/). POST /locations Select code sampleFetchcURL ```js const url = 'https://api.creatorain.com/v1/locations?dry_run=false'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"name":"Sexy Crab Duluth","address":"2416 Pleasant Hill Rd, Duluth, GA 30096","google_place_id":"example","plan":"paid","videos_per_month":4,"accepted_terms":"network-2026-10","opening_hours":{},"signature_dishes":[{"name":"example"}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request POST \ --url 'https://api.creatorain.com/v1/locations?dry_run=false' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "name": "Sexy Crab Duluth", "address": "2416 Pleasant Hill Rd, Duluth, GA 30096", "google_place_id": "example", "plan": "paid", "videos_per_month": 4, "accepted_terms": "network-2026-10", "opening_hours": {}, "signature_dishes": [ { "name": "example" } ] }' ``` - Live (crp\_live\_ keys) - Sandbox (crp\_test\_ keys) Scope `locations:write`. The store is created ON HOLD (`state: on_hold`): nothing recruits or books it until CreatoRain releases it. The plan is the account’s: on the paid plan `videos_per_month` is 2 to 10 at the locked price per video, and `deposit` quotes the half of month one (paid later at Checkout, never charged here); on the free plan it is exactly the free plan’s videos for its term, with no deposit. There is no store maximum. Creator selection is CreatoRain’s: a creator field (`min_followers`, `rules`, `approval_mode`, …) is `400 customization_not_supported`. The same place again answers `200` with `outcome: repeat` and the STORED plan (a create never updates one); a place another team of this account holds is `409 location_already_in_network`. ## Authorizations - **[bearerAuth](/reference/#bearerauth)** ## Parameters ### Header Parameters **Idempotency-Key** required string \>= 1 characters <= 255 characters /^\[\\x21-\\x7E\]+$/ As `Idempotency-Key`, and required here (a location create). Without it the answer is `400 idempotency_key_required`. A dry run needs one too: it writes no store row; the Idempotency-Key is still stored. ### Query Parameters **dry\_run** boolean `true` validates and quotes: the same refusals as a live call, and writes no store row; the Idempotency-Key is still stored. Ids are null. ## Request Bodyrequired Media typeapplication/json object **name** required string \>= 1 characters <= 300 characters ### Example ``` Sexy Crab Duluth ``` **address** required One of: - [string](#tab-panel-0-0) - [object](#tab-panel-0-1) string \>= 5 characters <= 400 characters ### Example ``` 2416 Pleasant Hill Rd, Duluth, GA 30096 ``` object **line1** required string <= 300 characters **city** required string <= 120 characters **state** required string <= 120 characters **postal\_code** string nullable <= 40 characters **country** string nullable <= 120 characters **google\_place\_id** string nullable <= 300 characters **plan** Absent means the account’s plan; another plan is 422 package\_not\_available. string Allowed values: paid free **videos\_per\_month** required Paid: 2 to 10. Free: exactly the free plan’s videos. Otherwise 400 videos\_per\_month\_out\_of\_range. integer ### Example ```json 4 ``` **accepted\_terms** The network terms version accepted string nullable /^\[a-z0-9\]\[a-z0-9.-\]{2,59}$/ ### Example ``` network-2026-10 ``` **opening\_hours** The store’s week object **signature\_dishes** Array <= 50 items One of: - [string](#tab-panel-1-0) - [object](#tab-panel-1-1) string <= 300 characters object **name** required string <= 300 characters ## Responses ### 200 A repeat of a live store (nothing written), or a dry run. Media typeapplication/json object **object** required string Allowed values: location **id** required Null on a dry run. string nullable **outcome** required string Allowed values: create repeat revive **livemode** required boolean **name** required string nullable **address** required string nullable **plan** required string Allowed values: paid free **videos\_per\_month** required integer nullable **term\_months** required Free: the free term. Paid: null, until stopped. integer nullable **price\_per\_video\_cents** required integer nullable **currency** required string Allowed values: USD **deposit** required object **cents** required The half of month one: videos\_per\_month x price\_per\_video\_cents / 2. Free: 0. integer nullable **charged** required Never charged by this call. boolean **state** required The network state; null on a dry run. string nullable **dry\_run** required boolean **account** required object **counting\_locations** required Live stores of this account after the call (a dry run - as it would be). integer **min\_locations** required integer **blockers** required Below\_minimum while counting\_locations is under min\_locations. Array #### Example ```json { "object": "location", "id": "loc_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e", "outcome": "create", "plan": "paid", "price_per_video_cents": 30000, "currency": "USD", "deposit": { "charged": false }, "state": "on_hold", "account": { "min_locations": 3 } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Idempotent-Replayed** string Allowed values: true True when this answer is the stored response to an earlier request with the same Idempotency-Key. ### 201 Created, or an ended store brought back (`outcome: revive`); on hold either way. Media typeapplication/json object **object** required string Allowed values: location **id** required Null on a dry run. string nullable **outcome** required string Allowed values: create repeat revive **livemode** required boolean **name** required string nullable **address** required string nullable **plan** required string Allowed values: paid free **videos\_per\_month** required integer nullable **term\_months** required Free: the free term. Paid: null, until stopped. integer nullable **price\_per\_video\_cents** required integer nullable **currency** required string Allowed values: USD **deposit** required object **cents** required The half of month one: videos\_per\_month x price\_per\_video\_cents / 2. Free: 0. integer nullable **charged** required Never charged by this call. boolean **state** required The network state; null on a dry run. string nullable **dry\_run** required boolean **account** required object **counting\_locations** required Live stores of this account after the call (a dry run - as it would be). integer **min\_locations** required integer **blockers** required Below\_minimum while counting\_locations is under min\_locations. Array #### Example ```json { "object": "location", "id": "loc_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e", "outcome": "create", "plan": "paid", "price_per_video_cents": 30000, "currency": "USD", "deposit": { "charged": false }, "state": "on_hold", "account": { "min_locations": 3 } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Idempotent-Replayed** string Allowed values: true True when this answer is the stored response to an earlier request with the same Idempotency-Key. ### 400 Parameter\_invalid (with `field`) or invalid\_json. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 401 Invalid\_key, test\_key\_on\_live or live\_key\_on\_sandbox. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 403 Scope\_missing or forbidden\_ip. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 409 Location\_already\_in\_network (another team of this account holds the place, or the same place under another name), idempotency\_conflict or idempotency\_in\_progress. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 422 Package\_not\_available (a plan other than the account’s, or a free-plan account bringing back a store that already ran its free term). Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 429 Rate\_limited (600 a minute per workspace, an onboarding create limit, or an address blocked after failed authentication), or slow\_down (an onboarding session polled too fast). Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Retry-After** integer \>= 1 Seconds to wait before retrying (at least 1). ### 500 Internal\_error (500) or service\_unavailable (503). The message never carries a cause. Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. ### 503 Service\_unavailable. A concurrent request wrote one of these locations; retry after `Retry-After` with the same key (it was not stored). Media typeapplication/json object **error** required object **type** required string Allowed values: invalid\_request\_error authentication\_error permission\_error idempotency\_error rate\_limit\_error api\_error **code** required string Allowed values: parameter\_invalid invalid\_json idempotency\_key\_invalid idempotency\_key\_required customization\_not\_supported videos\_per\_month\_out\_of\_range batch\_invalid terms\_not\_accepted invalid\_key test\_key\_on\_live live\_key\_on\_sandbox insufficient\_balance scope\_missing forbidden\_ip forbidden live\_key\_requires\_top\_up limit\_raise\_requires\_dashboard not\_found idempotency\_conflict idempotency\_in\_progress conflict location\_already\_in\_network external\_id\_conflict dispute\_open request\_too\_large address\_not\_verified not\_food\_business metro\_not\_served package\_not\_available account\_location\_limit commit\_limit\_exceeded top\_up\_exceeds\_feasible no\_saved\_card rate\_limited quota\_exceeded slow\_down internal\_error service\_unavailable **message** required string **field** The request field at fault string **doc\_url** required string format: uri **request\_id** required string format: uuid **items** Batch\_invalid only. Every refused location, by its index in the request. Array object **index** required integer **code** required One of the error codes above. string **field** string **message** required string #### Example ```json { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "doc_url": "https://www.creatorain.com/api/errors#scope_missing", "items": [ { "field": "locations.1.videos_per_month" } ] } } ``` #### Headers **Request-Id** string format: uuid This request’s id. Equal to error.request\_id; quote it to support. **Retry-After** integer \>= 1 Seconds to wait before retrying (at least 1).