AI-ready version:

Create an App

Description

This API allows you to create a new app for a specified company. Optionally, a sandbox version of the app can also be created with predefined settings. The app includes metadata like name, description, and sharing details.

Endpoint

POST https://impact.dots.eco/api/v1/app/add

Refer to Headers and Authorization for detailed instructions about authentication and required headers.

Parameters

Name	Required	Type	Description
`name`	Yes	`string (max_length=255)`	The name of the application.
`company_id`	Yes	`integer (max=10^10)`	The ID of the company associated with the application.
`share_title`	Yes	`string (max_length=255)`	The title for sharing content (e.g., email subject).
`share_body`	Yes	`string (max_length=255)`	The body text for shareable content or emails.
`logo`	No	`string (max_length=2048)`	The URL pointing to the app's logo.
`social_media_image`	No	`string (max_length=2048)`	The URL for an image used in social media shares.
`description`	No	`string (max_length=1000)`	A description of the app.
`download`	No	`object`	Contains optional fields: `title` and `url` for the download button.
`share_hashtag`	No	`string (max_length=255)`	A hashtag for social media sharing.

Example Requests

Minimal Request

curl --location --request POST 'https://impact.dots.eco/api/v1/app/add' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN' \
--data-raw '{
    "name": "Test App",
    "company_id": 12345,
    "share_title": "Check out this amazing app!",
    "share_body": "See how I'm making an impact."
}'

Full Example Request

{
    "name": "Super Impact App",
    "company_id": 12345,
    "share_title": "Join the Impact Revolution!",
    "share_body": "Learn how to make a difference with a sustainable lifestyle using our app.",
    "logo": "https://example.com/logo.png",
    "social_media_image": "https://example.com/social-image.png",
    "description": "A groundbreaking app designed to help businesses and individuals achieve their sustainability goals.",
    "download": {
        "title": "Download Now",
        "url": "https://example.com/download"
    },
    "share_hashtag": "#MakingImpact"
}

Responses

Example Successful Response

When the request is successful, the API returns a JSON object containing details about the created app. If sandbox creation is enabled, details about the sandbox app are also included.

{
    "name": "Test App",
    "app_id": "1111",
    "company_id": 12345,
    "sandbox_app": false,
    "logo": "https://impact.dots.eco/sites/default/logo.png",
    "social_media_image": "https://impact.dots.eco/sites/default/facebook.jpg",
    "description": "Description of the test app.",
    "download": {
        "title": "Download Now",
        "url": ""
    },
    "share_title": "Check out this amazing app!",
    "share_body": "See how I'm making an impact.",
    "share_hashtag": "#Sustainability",
    "autocreated_sandbox": {
        "name": "Test App - Sandbox",
        "app_id": "1112",
        "company_id": 12345,
        "sandbox_app": true,
        "logo": "https://impact.dots.eco/sites/default/logo.png",
        "social_media_image": "https://impact.dots.eco/sites/default/facebook.jpg",
        "description": "Sandbox instance of the app.",
        "download": {
            "title": "Test Download",
            "url": "https://impact.dots.eco"
        },
        "share_title": "Check out this sandbox app!",
        "share_body": "Experience the app's functionality in a sandbox.",
        "share_hashtag": "#SandboxDemo"
    }
}

Response Fields

Key	Type	Description
`name`	`string`	The name of the created app.
`app_id`	`string`	The unique identifier for the app.
`company_id`	`integer`	The ID of the company associated with the app.
`sandbox_app`	`boolean`	Indicates whether the app is a sandbox.
`logo`	`string`	URL pointing to the app's logo.
`social_media_image`	`string`	URL for an image on social media.
`description`	`string`	A short description of the application.
`download.title`	`string`	Text for the app’s download button.
`download.url`	`string`	URL linking to app downloads.
`share_title`	`string`	Title for shareable content/emails (e.g., email subject).
`share_body`	`string`	The body content for sharing emails or social posts.
`share_hashtag`	`string`	A hashtag associated with app sharing.
`autocreated_sandbox`	`object`	Details about the automatically created sandbox app, if any.
`autocreated_sandbox.name`	`string`	Name of the sandbox app.
`autocreated_sandbox.app_id`	`string`	The ID of the sandbox app.
`autocreated_sandbox.company_id`	`integer`	The company ID associated with the sandbox app.
`autocreated_sandbox.sandbox_app`	`boolean`	Indicates whether the app is a sandbox.
`autocreated_sandbox.logo`	`string`	URL pointing to the logo for the sandbox app.
`autocreated_sandbox.social_media_image`	`string`	Image for social shares of the sandbox app.
`autocreated_sandbox.description`	`string`	Description of the sandbox app.
`autocreated_sandbox.download.title`	`string`	Text for the sandbox app’s download button.
`autocreated_sandbox.download.url`	`string`	URL linking to app downloads for the sandbox app.
`autocreated_sandbox.share_title`	`string`	Title for sharing the sandbox app.
`autocreated_sandbox.share_body`	`string`	The body content for sharing the sandbox app.
`autocreated_sandbox.share_hashtag`	`string`	Hashtag used for sandbox app sharing.

Errors

Common Error Codes

422 Unprocessable Entity

Returned if required fields are missing or the provided data is invalid.

Message	Cause
`"You must provide a valid 'name' value to process."`	Missing or invalid `name`.
`"You must provide a valid 'company_id' value to process."`	Missing or invalid `company_id`.
`"The maximum length of [field] is [max_length] characters."`	Exceeds the maximum allowed length.
`"The maximum value of [field] is [max_value]."`	Integer value exceeds the permitted limit.

403 Access Denied

Returned if the user lacks proper permissions or the server imposes restrictions.

Message	Cause
`"You can send one request every 5 seconds."`	Rate limit exceeded.
`"Access denied: you don't have permissions to create an application."`	Insufficient privileges.

Notes

Ensure the required fields (name, company_id, share_title, share_body) are included in your request payload.
Sandbox apps are automatically created only if the system and privileges support them.
For further details, consult the Headers and Authorization documentation.