===== Optional XML Feed Fields =====

=== <customId> ===
  * requirement: OPTIONAL – STRONGLY RECOMMENDED
  * values: integer
  * **special feature**: __it is used for POST UPDATES__! Read: [[Updating Posts via API]]
  * description: it is provided for users to enter their own unique identifier for the post (internal ID). It is an optional tag and if received it is used by ClickaPost to make sure duplicate posts are not getting saved in the system. When provided, it is stored and associated with other post data so later on we can use it for comparison. This is mostly intended for people who do not only submit the new data via XML but rather run some kind of a “SYNC” of all their posts and ClickaPost. This way – only new posts will be submitted, __any posts already in the system and matching your <customId> will be automatically updated with the new post data provided__.
  * if NOT set or set incorrectly: discarded and not used / all posts published as new (no updates possible in the future on the posts without <customId>)

=== <subtitle> ===
  * requirement: OPTIONAL
  * values: alphanumeric content of 60 characters max [NO HTML ALLOWED]
  * description: post’s subtitle
  * if NOT set: not stored

=== <allowComments> ===
  * requirement: OPTIONAL
  * values: true or false
  * description: allows users to set if they wish to allow comments on the post or not
  * if NOT set or set incorrectly: defaults to true (allowing users to post comments)

=== <allowAnonymousComments> ===
  * requirement: OPTIONAL
  * values: true or false
  * description: allows users to set if they wish to allow anonymous (non-registered) user comments on the post or not
  * if NOT set or set incorrectly: defaults to true (allowing anonymous users to post comments)

=== <duration> ===
  * requirement: OPTIONAL
  * values: specific set of values per ClickaPost sub-category (1 week, 2 weeks), etc.
  * description: correct values can be found using the GET method
  * if NOT set or set incorrectly: the post maximum duration will be chosen

=== <showPriceValue> ===
  * requirement: OPTIONAL
  * values: floating point numeric value preceded with a currency symbol (ex. $20,000, $5000, or $5.00)
  * description: defines the price of the item listed, and depending on category it can also represent a set of other things like: minimum salary requested (in resumes category), salary offered (in jobs category), entrance fee for an event, etc.
  * if NOT set or set incorrectly: it will not be stored or shown at all
  * if not preceded with a currency symbol like ($) or (€), default currency ($) will be stored automatically (unless in <strict> mode in which case the post will fail)

=== <showPriceType> ===
  * requirement: OPTIONAL
  * values: one time, per hour, per day, per month, per quarter, per year, or best offer, or as agreed, or more
  * description: it’s the text that shows up right after the <showPriceValue> option so it adds an extra meaning to the price itself (ex. “per hour” setting can be used for stating “$30/hr” rate for a job application). Won’t be shown if <showPriceValue> is not set.
  * if NOT set or set incorrectly: it will not be stored or shown at all

=== <stateProvince> ===
  * requirement: OPTIONAL
  * values:  it can be either the unique ClickaPost State/Province ID, 2-letter US state (OH, NY) or a state name (up to 30 characters) which ClickaPost system will try to match with the required <country> variable specified before.
  * description: represents where the post is being stored under (State ID can be found using the GET method)
  * if NOT set or set incorrectly: it will not be stored or shown at all (post will only have <country> data)

=== <city> ===
  * requirement: OPTIONAL
  * values: it can be either the unique ClickaPost City ID, or a city name (up to 35 characters) which ClickaPost system will try to match with the required <country> and <stateProvince> variables provided before. If <country> and <stateProvince> are not defined <city> will be discarded.
  * description: represents where the post is being stored under (City ID can be found using the GET method)
  * if NOT set or set incorrectly: it will not be stored or shown at all (post will only have <country> and, if set, <state> data)

=== <keywords> === 
- an optional tag used to encompass any subcategory-specific keywords (<keyword>) for the post. Furthermore <keyword> tags are stored in tag pairs out of which if any are to be set – BOTH <keyword> and <value> are required. 

NOTE: These are NOT freely set keywords but rather precisely defined for each and every subcategory and can be found using the GET methods. Every ClickaPost category has its own set of allowed keywords.

==<keyword>==
  * specific value from the set of keywords defined for the <category> the user is posting into – available via GET method
**<value>**
  * specific value for the particular keyword chosen – some allow specific values to be inserted, other keywords are free form and allow you to provide the keyword yourself

If any keyword pairs are missing or are set incorrectly – they will simply be discarded and not used
Here’s an example of couple of keywords available for Vehicles->Cars & Trucks subcategory:

<code xml>
<keywords>
	<keyword> 
		<key>Car make</key>
		<value>Honda</value>
	</keyword>
<keyword> 
		<key>Car model</key>
		<value>Accord</value>
	</keyword>
</keywords>
</code>

=== <photos> ===
- another optional tag used for storing images with the posts. It should contain a list of <link> tags to the images for the post. Note: ClickaPost does NOT link to these images, rather, ClickaPost will DOWNLOAD all of them and insert them into the posts; for this reason, it is very important for images to be freely available on line without any password protection and such (i.e. reachable from a public computer without any authentication).

==<photo>==
  * accepts a valid HTML link to the image, ex: http://some.domain.ext/image1.jpg
  * furthermore: images can be jpg, jpeg, and png ONLY. Gif, Tiff and others are not accepted
  * if any links are set incorrectly, non reachable, or the images are larger than 1.5MB or of wrong file type – they will be discarded and not used

== <defaultPhoto> ==
  * requirement: OPTIONAL
  * values: file name of the photo is an optional parameter containing the filename of the main image for the post (from the list of linked image files in <photos> section (if link is http://some.domain.ext/image1.jpg, <defaultPhoto> tag could be image1.jpg).
  * description: used to set the main image shown on your post when displaying only limited post details to users during search results.
  * if NOT set or set incorrectly: if any images are provided – ClickaPost will set the first image as the default image. If none are provided – none will be set as default.

=== <videos> ===
- another optional tag used for storing videos with the posts. It should contain a list of <link> tags to the videos for the post. Note: ClickaPost does NOT link to these videos, rather, ClickaPost will DOWNLOAD all of them, convert them into Flash Video format, and insert them into the post; for this reason, it is very important for these videos to be freely available on line without any password protection and such (i.e. reachable from a public computer without any authentication).

==<video>==
  * accepts a valid HTML link to the video, ex: http://some.domain.ext/video.mpeg 
  * furthermore: most video formats are supported by ClickaPost so there should be no issue uploading any type of a video. As of writing of this documentation, videos can be with following extensions [*.mov; *.wmv; *.avi; *.mpg; *.mpeg; *.mp4]
  * if any links are set incorrectly, non reachable, or the videos are larger than 100MB – they will be discarded and not used

=== <embededVideos> === 
- an optional tag used to encompass any <video> you may have on video sharing web-sites (like YouTube, MetaCafe, WellcomeMat, etc.) into your post. Furthermore <video> tags are stored in tag pairs out of which if any are to be set – BOTH <service> and <link> are required. While <service> tag is specifically set for the services ClickaPost supports (the list of which is available via GET method), the <link> tag is completely up to you (since it refers to your videos).

==<service>==
  * specific value for the 3rd party video services ClickaPost supports. At the time of this document writing they are (bliptv, google, leak, metacafe, myspace, veoh, wellcomemat, yahoo and youtube  - respectively meaning: Blip.TV, Google Video, Live Leak, MetaCafe, MySpace, Veoh, WellcomeMat, Yahoo Video and YouTube).
- The most up to date list is always available via GET method.

==<link>==
  * the link to your video on any of the video <service> web sites we support. Note: not a link to the web page where  your video can be found, but rather, a DIRECT link to the video itself!
  * Example: http://www.youtube.com/v/UyU9OLqQ8XA

If any <video> pairs are missing or are set incorrectly – they will simply be discarded and not used
Here’s an example for linking two embedded videos:

<code xml>
<embededVideos>
	<video> 
		<service>youtube</service>
		<link>http://www.youtube.com/v/UyU9OLqQ8XA</link>
	</video>
	<video> 
		<key>wellcomemat</key>
		<link>http://www.wellcomemat.com/wm_video/AA89E62A78</link>
	</video>
</embededVideos>
</code>

=== Next Step ===
  * [[The STRICT Tag]] - learn about the <strict> tag and how it affects XML processing
  * [[XML Response]] - see how to interpret XML responses returned after your XML has been parsed
  * [[What happens after XML is processed]] - get familiar with internal workings of ClickaPost
  * [[Updating Posts via API]] - not every post has to be a new post, here's how to update them instead