--- title: "Forecasts.create" method: POST path: "/entities/Forecasts" tags: ["Forecast"] --- # Forecasts.create `POST /entities/Forecasts` ## Request - Base URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id` - URL: `https://us-east.api.coevera.com/api/v100/rest/spaces/your_space_id/entities/Forecasts` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a Forecast record. ## Query parameters - `validation-level` integer ## Request body - CreateForecastInput: Field values of a new Forecast record. - `modified` string, date-time: Last modification time. - `created` string, date-time: Creation time. - `description` string: Free-text description shown alongside the forecast. - `name` string, required: Name of the entity and its default text representation. - `owner_id` string, uuid, required: Id of the owning user. - `settings` object, required: Forecast configuration as a JSON object conforming to the BetterForecastSchema type: currency, period (year + quarter/month), breakdown levels (type), items and quotas, and column layout. Validated on write. Full structure: https://developers.coevera.com/reference/graphql/types/b/#BetterForecastSchema This payload conforms to the `BetterForecastSchema` JSON Schema (see the linked schema). - `share_mode` 0 | 1 | 2 | 3: Who besides the owner can access the forecast. Updating it to AllEdit shares the forecast with the users and sales units it covers (see shared_clients and shared_units) and stores the mode as Standard. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `share_mode_params` string: Legacy additional sharing options; kept with the record but no longer applied. - `revision` integer: Revision when entity was lastly changed. - `shared_clients` object[], required: Users granted shared access to this forecast (custom share mode). - `id` string, uuid: Id of the related Client record. - `shared_units` object[], required: Sales units granted shared access to this forecast (custom share mode). - `id` string, uuid: Id of the related SalesUnit record. ## Response `201` The created Forecast record. - object - `success` boolean: True when the request succeeded; false on error. - `data` Forecast: Sales forecast that sums an amount over the opportunities of a pipeline for a period, broken down by levels such as sales units and users. - `is_delete_protected` boolean, required: True when the record is protected against deletion because it must always exist in the space. Deleting a record that is not protected can still fail on other checks. Read-only. - `id` string, uuid, required: Unique identifier of entity. - `is_deleted` boolean: Specifies if the entity is considered deleted. - `modified` string, date-time: Last modification time. - `created` string, date-time: Creation time. - `field` string, uri, required: Field whose value is summed when computing forecast amounts (typically a currency field on Opportunity). Related Field record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Field' for its fields. - `owner` string, uri, required: User who owns the forecast. Related Client record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Client' for its fields. - `pipeline` string, uri, required: Pipeline whose opportunities the forecast aggregates. Related Pipeline record, returned as the URI of the record. With the 'expand' parameter the full record is returned instead; see 'Pipeline' for its fields. - `description` string: Free-text description shown alongside the forecast. - `end_date` string, date, required: Last date covered by the forecast period. - `field_id` string, uuid, required: Id of the aggregation field. - `name` string, required: Name of the entity and its default text representation. - `owner_id` string, uuid, required: Id of the owning user. - `pipeline_id` string, uuid, required: Id of the pipeline whose opportunities the forecast aggregates. - `settings` object, required: Forecast configuration as a JSON object conforming to the BetterForecastSchema type: currency, period (year + quarter/month), breakdown levels (type), items and quotas, and column layout. Validated on write. Full structure: https://developers.coevera.com/reference/graphql/types/b/#BetterForecastSchema This payload conforms to the `BetterForecastSchema` JSON Schema (see the linked schema). - `share_mode` 0 | 1 | 2 | 3: Who besides the owner can access the forecast. Updating it to AllEdit shares the forecast with the users and sales units it covers (see shared_clients and shared_units) and stores the mode as Standard. Integer enum value: 0 - Standard, 1 - Private, 2 - AllView, 3 - AllEdit - `share_mode_params` string: Legacy additional sharing options; kept with the record but no longer applied. - `start_date` string, date, required: First date covered by the forecast period. - `type` object, required: Order of forecast levels as a JSON array (e.g. ["Units", "Users"]). Each level adds a grouping dimension to the breakdown. - `revision` integer: Revision when entity was lastly changed. - `shared_clients` string[], required: Users granted shared access to this forecast (custom share mode). - `shared_units` string[], required: Sales units granted shared access to this forecast (custom share mode). ## Other responses - `400`: Bad request: a bad or unknown parameter (codes 117, 118), a missing permission (code 50), conflicting data (code 2002) or any other API error. The REST API answers 400 where others answer 403 or 409; check `code`. - `401`: Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED). - `422`: Validation failed (code 40000, with the failing fields) or a required parameter is missing (code 119). By default one failed item fails a whole batch and nothing is written. - `429`: Too many requests (code 182). Wait for the seconds in Retry-After, then retry. - `500`: Unexpected server error (code 1000, ERROR_UNKNOWN). --- [API](https://skmtc.dev/coevera/apis/coevera-crm-api.md) - [All operations](https://skmtc.dev/coevera/apis/coevera-crm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coevera/apis/coevera-crm-api/revisions/40ebbc83f179?raw)