# Data Takeout This guide describes how to use the Realpad Takeout API to back up the data stored in the system. Both structured data (such as lists of customers, deals, etc) and files uploaded to the CRM (unit plans, contract scans, ...) can be automatically retrieved this way. You are encouraged to implement an automatic backup system that will download the data from our server at any frequency you prefer, and use the data as a source for a reporting solution, or any other purpose. ## Prerequisites To use these APIs you need to have the ability to execute HTTP requests either from the command line or from some scripting language. Please contact us if you need our help with achieving this. ## OpenAPI specification Lives [here](https://openapi.gitbook.com/o/UuR2VSBNcvrkwmPVWwiM/spec/realpad-api-takeout.yaml). ## Request First of all please contact to obtain the credentials to use the Takeout API endpoints. You will perform **POST** requests over **HTTPS** and then store the resulting data. Most of the Takeout endpoints have just 2 parameters, both required: `login` and `password`. *Example call in **cURL:*** ```bash curl \ --data "login=...&password=..." \ --output customers.xls \ https://cms.realpad.eu/ws/v10/list-excel-customers ``` ## Response #### Entity Relationship Overview The following diagram shows how the entities exported by the Takeout API relate to each other via their ID columns. Each box represents one export endpoint, and the arrows indicate which ID columns can be used to join data across exports. **Legend:** * **PK** — the entity's own identifier * **FK** — a foreign key that can be joined to another export * **"CS · default on/off"** — the column is subject to Column Selection and may be absent if the API user has de-configured it (see Column Selection below) * **"enum"** — a lookup/classification ID, not a joinable entity reference * **"→ User"** — references a User entity that is not directly exported by the Takeout API
{% file src="/files/Xz1ipC2oDFB46csgliQH" %} #### Column Selection Some exports support **Column Selection**, which allows the API user to configure which columns appear in the output and in what order. Columns marked as "CS" in the diagram above may be absent if the API user has removed them from their column set. Most CS-dependent ID columns are **included by default** — they will be present unless explicitly de-configured. The exception is **Task → Inquiry ID**, which is off by default. Columns listed as "always present" have no Column Selection mapping and will always appear at the end of the export, regardless of configuration. ### Endpoints with XML payload **list-resources** This endpoint provides a full list of all the files that were ever uploaded to the CRM for the given real estate developer, whether it’s unit plans, contract scans, invoices, or any other similar data that started out as a file on someone’s computer before being imported into Realpad. We call all such files ***resources***, and the `list-resources` endpoint shows them like this: The root element is ``, sub-elements look like this: ```makefile ``` * `uid` is the unique identifier of this resource, by which it can be retrieved using `get-projects`. * `content-type` is the MIME type of the file, resolved when uploaded to the system (it's the best guess). * `file-name` is the original file name when it was uploaded to the system. * `size` is the file size in bytes. * `crc` is the CRC32 checksum of the file. The basic use case for this endpoint is to back up all the files from the CRM to some storage on local infrastructure. For that, you might want to build a tool that will regularly fetch this endpoint, compare its results to the files you already have stored, and fetch the ones that are missing. You may rely on UID as the unique identifier to distinguish between the files. You can fetch resources using **HTTP GET** by retrieving a URL in the following form: `https://cms.realpad.eu/resource/` *Example call in **cURL:*** ```bash curl \ --output cached_resource \ https://cms.realpad.eu/resource/bd5563ae-abc... ``` ### Endpoints with a binary payload All of these endpoints return a single Excel file with a `.xls` extension, containing all the relevant data stored in our system. These endpoints behave just like `get-resource`, in that the HTTP headers contain a reasonable file name (e.g. when running from a web browser). **Newer Excel format:** if an extra parameter `xlsx` is sent with a non-empty value, Takeout API will instead provide the data in the Excel newer `.xlsx` format. **Column identifiers:** by default, the Excel file will have the header row built in the exactly same way as if the given user clicked a button to download the file in the user interface. This means that each column will have header titled in the language of the invoking user, and the title will be a user-friendly string. In case you need to further work with the data in a programmatic way, we strongly recommend sending an extra parameter to the AP call: its name is `headermode` and there are several possible values controlling how the header will appear in the output: * `labels` will export headers as one row with the localized column titles. This is the default behavior in case the parameter is omitted. * `ids` will export headers as one row with the columns identified by special strings that are guaranteed to be stable. **We urge you to use this value for the best long-term compatibility.** * `labels_ids` will export headers as two rows: localized names first, special strings second. * `ids_labels` will export headers as two rows: special strings first, localized names second. {% hint style="info" %} If you call the endpoints too often, you will receive `429 TOO MANY REQUESTS` and the body of the response tells you when it will be possible to call it again. **See also:** [Authentication & Error Handling](/integrations/introduction/authentication-and-error-handling.md) for details on the `Retry-After` header, banning behavior, `415 Unsupported Media Type`, and other shared error responses. {% endhint %} **list-excel-projects** Each row represents one **Project**. Always-present ID columns: * Project ID **list-excel-products** Each row represents one **Unit** (also called Product). Always-present ID columns: * Unit ID * Type ID (enum) * Availability ID (enum) * Project ID → Projects * Deal ID → Deals See the appendix for the unit type and availability enums. **list-excel-project-units-history** Accepts an additional required parameter `projectid`, which has to be a valid project ID from the Realpad database. Each row represents one **Unit History Entry** (a snapshot of a Unit's state at the time of a change). Always-present ID columns: * Project ID → Projects * Unit ID → Units * Changed By ID → User * Deal ID → Deals The first column contains the timestamp of when the given unit started containing the data on the given row. The second column contains the name of the user who caused that data to be recorded. **list-excel-customers-contacts** Each row represents one **Customer Contact**. Always-present ID columns: * Customer\~Contact ID (referenced as "Customer ID" in other exports) * Owner ID → User **list-excel-inquiries** Each row represents one **Inquiry**. Always-present ID columns: * Inquiry ID (column named "Inquiry") * Customer ID → Customer Contacts * Referral ID (enum) * Status ID (enum) **list-excel-favorite-units** Each row represents one **Favorite Unit** (a Customer's expressed interest in a specific Unit). Always-present ID columns: * Inquiry ID → Inquiries * Customer ID → Customer Contacts * Unit ID → Units * Project ID → Projects * Sales Agent ID → User * Created By → User **list-excel-prereservations** Each row represents one **Pre-reservation** (a time-limited hold on a Unit before a Deal is created). Always-present ID columns: * Customer ID → Customer Contacts * Unit ID → Units * Project ID → Projects **list-excel-tasks** Each row represents one **Task**. Always-present ID columns: * Task ID * Customer ID → Customer Contacts * Salesman ID → User (not exported) Column Selection ID columns (default: off): * Inquiry ID → Inquiries **list-excel-events** Each row represents one **Event** (a logged interaction or activity). Always-present ID columns: * Event ID * Customer ID → Customer Contacts * Inquiry ID → Inquiries * Unit ID → Units * Project ID → Projects **list-excel-business-cases** Each row represents one **Deal**. Always-present ID columns: * Customer ID → Customer Contacts * Salesman ID → User * Status ID (enum) * Lifecycle ID (enum) * Main Unit ID → Units * Additional Customer IDs → Customer Contacts * Additional Product IDs → Additional Products * Project ID → Projects Column Selection ID columns (default: on): * Deal ID * Inquiry ID → Inquiries **list-excel-deal-documents** Each row represents one **Deal Document** (a contract or other document associated with a Deal). Always-present ID columns: * Document ID * Customer ID → Customer Contacts * Salesman ID → User Column Selection ID columns (default: on): * Deal ID → Deals **list-excel-additional-products** Each row represents one **Additional Product** (an extra item or service sold alongside a Deal). Always-present ID columns: * Additional Product ID * Type ID (enum) * Payment ID → Prescribed Payments Column Selection ID columns (default: on): * Deal ID → Deals **list-excel-payments-prescribed** Each row represents one **Prescribed Payment** (a scheduled payment that a customer is expected to make). Always-present ID columns: * Payment ID * Type ID (enum) Column Selection ID columns (default: on): * Deal ID → Deals **list-excel-payments-prescribed-lines** Each row represents one **Prescribed Payment Line** (a detail row within a Prescribed Payment, allocating an amount to a specific Unit). Always-present ID columns: * Line ID * Deal ID → Deals * Payment ID → Prescribed Payments * Unit ID → Units **list-excel-payments-incoming** Each row represents one **Incoming Payment** (an actual payment received from a customer). Always-present ID columns: * Payment ID * Prescribed Payment ID → Prescribed Payments Column Selection ID columns (default: on): * Deal ID → Deals **list-excel-inspections** Each row represents one **Inspection** (a scheduled or completed handover or technical inspection for a Deal). Always-present ID columns: * Row ID Column Selection ID columns (default: on): * Deal ID → Deals **list-excel-defects** Each row represents one **Defect** (a reported issue found during an Inspection or warranty period). Accepts an additional optional parameter `mode`. By default, all the Deal Warranty Claim Defects are returned. Certain developers will also see the Communal Areas Defects here by default. If `mode` is specified, other Defects can be returned. Available modes are: `DEAL_DEFECTS`, `DEAL_DEFECTS_COMMUNAL_AREA`, `DEAL_DEFECTS_COMBINED`, `INSPECTION_DEFECTS`, `INSPECTION_DEFECTS_COMMUNAL_AREA`, `INSPECTION_DEFECTS_COMBINED`. Always-present ID columns: * Defect ID Column Selection ID columns (default: on): * Deal ID → Deals ### Deprecated endpoints **list-excel-customers** {% hint style="warning" %} Don't use this endpoint if the real estate developer was migrated to Multiple Inquiries. {% endhint %} The last column contains the unique customer ID from the Realpad database. **list-excel-sales-status** {% hint style="warning" %} Don't use this endpoint if the real estate developer was migrated to Multiple Inquiries. {% endhint %} The last column contains the unit ID from the Realpad database. > **Warning: deprecation notice** - originally we had an endpoint called `list-excel-unit-history`. This was working in an inefficient way, fetching only one unit at a time, which for typical use cases meant the necessity to call the endpoint over and over for many units. While we currently don't have a specific deadline of removing the legacy endpoint, we urge you to consider it deprecated and replace it with the new one. ## Appendix Unit status enumeration * 0 - free. * 1 - pre-reserved. * 2 - reserved. * 3 - sold. * 4 - not for sale. * 5 - delayed. Unit type enumeration * 1 - flat. * 2 - parking. * 3 - cellar. * 4 - outdoor parking. * 5 - garage. * 6 - commercial space. * 7 - family house. * 8 - land. * 9 - atelier. * 10 - office. * 11 - art workshop. * 12 - non-residential unit. * 13 - motorbike parking. * 14 - creative workshop. * 15 - townhouse. * 16 - utility room. * 17 - condominium. * 18 - storage. * 19 - apartment. * 20 - accommodation unit. * 21 - bike stand. * 22 - communal area. * 23 - non-residential unit - other. * 24 - berth. * 25 - construction right. * 26 - villa. * 27 - technical space. * 28 - outdoor parking position for motorbike. * 29 - property management unit. * 30 - attic. * 31 - backyard. * 32 - terrace. * 33 - cubicle. * 34 - tenement house. * 35 - paved area. * 36 - garage position. * 99 - other. ‍ {% @mailchimp/mailchimpSubscribe cta="Sign up to receive updates!" %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dev.realpadsoftware.com/integrations/data-takeout.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.